Sebastian <[email protected]> writes:
> recently I've started getting into Python and Django programming as
> well as shell scripting.
>
> I was wondering is there any rule or guide on good practice on how to
> comment code?
No, You can find an awful lot of opinion out there, but there is no
actual rule you can use to guide you.
On that basis, what follows is obviously my personal opinion. In my
case this is based on ~ 12 years of experience, in a wide range of
environments, which means they work for me — but not necessarily for
you.
> For me and my current knowledge state, very low I would say :-), I do
> a lot of commenting. sometimes more than one line comments on one line
> code. Now I was wondering if I should place the comments before the
> actual code line, after or at the end.
Generally, before the code, or perhaps on the same line. It is very
uncommon to run into code where comments come after the code, and it
would be much easier to miss the comment entirely in that case.
I suspect you are commenting too much in your code, though, if you have
more comments than actual code. (Well, that, or you are writing APL or
some equally dense language, in which a statement can comprise hundreds
or even thousands of logical operations. ;)
As a rule of thumb comments serve two purposes in code: they document
the high level design of the code, and they document the intimate detail
of implementation.
For high level design a single block, at the start or end of the module,
is generally best. Something like the manual page structure is
generally useful; it covers what a reference manual would reasonably
include.
This is also where you should include, for example, notes on the overall
performance of the module, why you selected the high level algorithms,
and so forth.[1]
It sounds like you are mostly talking about the intimate details of
implementation, though, rather than the high level stuff.
At that level you want to explain the *why* of the code: not the high
level stuff (this is a shell sort), but the low level stuff (this
mangling of the name is to handle quoting for the next three lines...)
Your audience here is someone from the future: in six months, when the
script needs to change, someone has to come back and make changes.
After that time even you will not remember exactly why you did things
the way you did, or what the hacks you introduced were. So, you want
the comments to guide you there.
So, write for someone who needs to know *why* something is done the way
it was. Don't comment the obvious; this is never useful:
int x = y * z; // x is y multiplied by z
This, however, is a critical comment:
# baz(1) passes the name to a subprocess via sh -c, performing a
# second round of filename expansion. We work around that here.
$fname =~ s/"/"\\""/gi;
What that does is explain, to me, *why* I wrote that code. It doesn't
try to tell me what it does — I can read that and see that it introduces
some quoted double-quotes — but rather why it matters that I do that.
> I like commenting in line after the code as it makes the code more
> easy to read - for me... But I like commenting lines preceding the
> code line as it keeps the lines itself short...
Generally, I have found code readability to be one of the most important
factors here. Select a style that enhances the ability of a random
third party to read the code, rather than looking for a hard and fast
rule.
> I think that most would say it comes down to personal preference but I
> was wondering at the same time if there are some rules I should get
> used to right from the start.
Understanding *why* the comments are there is generally the biggest step
to getting them right, I find. :)
Regards,
Daniel
Footnotes:
[1] If you find that you have too many of those in a single module or
script to document at this level that is, in my opinion, a pretty
strong hint that you should be writing two separate modules. :)
--
SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
