Code Documentation Project

From GoboLinux Knowledge Base

Hello everybody,

here we'd like to gather all the information needed to contribute to the Code Documentation Project, which simply consists in the effort of commenting every single script used in GoboLinux, thus making scripts hacking easier for anyone who really wanted to get involved, but never "jumped in" due to being scared by the infamous "one char variables" and the not-so-nice "bash monstrosities" :)

Contents 1 A bunch of simple rules 1.1 Comment format for shell scripts (may change) 1.2 Shell types 2 List of scripts 3 Other resources

[edit] A bunch of simple rules

Here's a (not definitive) list of advices, purely syntactical or more "structural"/"logical", which should be followed when commenting gobo scripts. We tried to follow Python's specifications regarding python comments, while bash ones are still "in progress", mainly because we're searching for some way to make them easily parseable by some (to do) script which in turn could generate html pages, man pages, and so on.

To look at a first example, please take a look here (this is the code the comments below refer to). Please note that it is very incomplete, and we linked it just to show you some "real" code.

So far, our suggestions are:

• Adhere to the PEP 8/257 standards when commenting Python scripts.
• The most helpful comments are the ones that explain the arguments of a function and what do they return. When commenting dynamically typed languages (such as Python or Lua) it's also useful to comment what are the expected types for arguments and return values (thanks to Hisham Muhammad).
• Too much comments can become a maintenance burden, and if the effort of maintaining them rises, then they may become out of sync with the code and end up doing more bad than good. The comment block at lines 285-323 is great, but trivial comments such as line 165 should be avoided. On the other hand, comments like line 363 are great because they explain the intention of the code (i.e., "why" it does, instead of "what" it does) (thanks to Hisham Muhammad).
• Avoid comments like line 254: when something is not understood, just leave it uncommented. This way someone else can notice more easily that a particular part of the code was left unexplained (thanks to Hisham Muhammad).

* My suggestion is to also try to be as short as possible.

• Of course, if you're going to hack some script please update it when done with comments to your newly added functionalities!

[edit] Comment format for shell scripts (may change)

When commenting shell functions this scheme should be used:

Description:
    What the function does.
Arguments:
    argument1 -- type : description
    argument2 -- type : description
    [...]
Output:
    type : description
Return:
    value : description
    value : description
    [...]
Notes:
    Here must go notes about side effects and stuff users should remember when using it.
Usage:
    Function's synopsis
Example:
    Call example of the function.

The "Notes" section is optional. Use the "none" keyword when there's no output or no returned value.

Also, a brief section following more or less the same scheme should be put at the very beginning of the file, just after the sha-bang line (#!/bin/bash). This is used to describe what the script as a whole does, if something.

Description:
    What the program does.
Notes:
    Here must go notes about side effects and stuff users should remember when using it.
Usage:
    Program's synopsis
Example:
    Call example of the script.

"Notes" and "Examples" are optional.

[edit] Shell types

Here's a list of types to use when describing functions' arguments.

• array  : A bash array of the form <name>=( "arg1" "arg2" ... "argn" )
• char  : A single character
• directory : A directory
• file  : A file name
• function  : A function expected to be called with arguments
• lambda  : A chunk of code expected to be executed directly
• list  : A space separated list of strings
• number  : A number
• string  : A string

[edit] List of scripts

This is the list of the currently "adopted" scripts, the ones we're commenting at the moment. Every script is assigned to a single person for convenience, but everybody's encouraged to contribute.

Name	Assigned to
CheckDependencies	Daniele (macco)
OptionParser	Daniele (macco)
ExtractComments	Aitor (A_Tuin)
Archive	Aitor (A_Tuin)
String	Daniele (macco)
Script here	Name here

We suggest you to check the whole gobo tools' svn trunk here, and to start from the Scripts/Functions dir, since here reside many of the scripts almost every gobo tool uses, some way or the other :)

[edit] Other resources

• If you want to know more about the project, join us on the users' mailing list. In the specific take a look at this thread. Feel free to contribute with ideas and proposals, everyone is well accepted ;)

• Did you document some code and want to share it with us? Then please create a patch for it and either mail it to the previously mentioned topic, or contact us on our irc channel #gobolinux.

Be sure to check this page frequently, as the work is in a very early stage, and guidelines could change daily! Thanks in advance to everybody who will help us in any way. :)