HLL overview

From Idiki

Contents 1 The idea 2 Example 3 Notes 4 See also

The idea

HLL overview is a proposal of a coding practice to improve the readability and comprension of the source code of a project.

The idea is to write an overview of the source code using a High Level Language, or more properly a pseudo-code language.

The overview should describe the basic structure of the sources and their flow of execution, explaining what functions are called when a particular event happens. In other words, the overview should clarify how the sources work and how they tie together.

Visually, the HLL overview is something like this. It gives a general, high level and immediate overview of the code.

The overview should use the WoC syntax, if possible.

The filename of the overview of the whole source code should be package.psy, where "package" is the name of the project and ".psy" stands for "Python pseudo-code". OVERVIEW.psy is another alternative.

It is also possible to write an overview of a single source file. In this case, the name would be source.psy, where "source" is the name of the relative source file.

Example

Take for example the OpenSSH source code. A (very tight) excerpt of the overview of sshd (the daemon) would be:

-- sshd.psy --
...
	import openssl

	load private host keys
		:key_load_private:
	
	Fetch our configuration
		:initialize_server_options:
		:load_server_config:
		:parse_server_config:

	if  a new connection has been established,
		sshd.c:1505
		:sshd_exchange_identification:

		if  authenticated:
			sshd.c:1732
			:do_authenticated:
	
	Terminate the connection with
		:packet_close:

	If  a SIGTERM is received,
		set :received_sigterm: = SIGTERM
		in this way :server_loop: will break

	exit(0)
...
-- sshd.psy --

Take sshd.psy as an example. In the real world, it should be more elaborated and commented,

Other examples:

• Overview of the Vim WoC client: [1]

Notes

Using the WoC syntax, it is possible to generate graph, following their connections and relationship. Again take as an example this

See also

• WoC

• Linux kernel net overview [2]

• HLL overview of the Vim WoC client: [3]