Re: [SLUG] comments in scripts and source code
Prefer factoring functions and methods out than using comments; the
functoin name is a much better description of the code it contains
than a leading comment on a block; e.g.
# Get data from cache
data = cache.get('foobar')
versus
def GetCacheData():
return cache.get('foobar')
Not terribly obvious in this trivial example, but you save a comment
and improve the readability of the code.
The second bit of advice is to use docstrings in Python when possible,
e.g to document these new methods if necessary:
def GetCacheData(frob=None):
"""Gets data from the local cache instead of from the data store.
The optional string argument frob specifies the name of the cache to
retrieve from, defaulting to the common cache.
"""
if frob:
return cache.get(frob)
else:
return cache.get('common')
which also has the great benefit that things like help() work, and
documentation is easier to generate.
2009/1/12 Sebastian :
> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA1
>
> Hi all,
>
> 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?
>
> 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.
>
> 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...
>
> 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.
>
>
> Cheers,
>
> seb
>
> -BEGIN PGP SIGNATURE-
> Version: GnuPG v1.4.7 (MingW32)
> Comment: http://getfiregpg.org
>
> iD8DBQFJaowNMuBzgG5z7F8RAqZoAJ9Pzw3SRaes6LOdlU4bOqCQSZPFVACghmIG
> NhFonZutl3aBKUneNvtlDOE=
> =fJ7n
> -END PGP SIGNATURE-
> --
> SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
> Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
>
--
SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
2009/1/12 justin randell :
> i agree with the replies to this thread already.
>
> the only thing i'd add as advice to a new programmer - try to avoid
> the need for comments by making the code as human-readable as
> possible. yeah, this may seem like not quite what you were asking, but
> i think its part of the same problem.
>
> so:
>
> - try to make variable names, function names, etc, as meaninful as
> possible within the constraints of the language and keystroke-sanity
> - whenever possible, avoid magic numbers/strings, and define a
> variable/constant with a meaningful name
This is EXACTLY the advice I try to push any programmer around me
who'd listen to follow. Well said!
The idea is that comments tend to be unmaintained. Unless the coder is
some maniac who keeps making sure that the comments are relevant EVERY
time they change a line of code, the intelligent reader of the
comments will eventually lose trust in them and then they start
hindering the code maintenance more than help ("is this comment still
relevant? It says that it uses 'quick sort' but this looks like bubble
sort, is it because the comment refers to another part of the code
(maybe in one of the called routines) or is it because the comment is
out of date?").
That's sort of related to the additional overhead of generally
maintaining comments which just repeat what a well written code should
say anyway.
Instead, as Justin says, if you want to be pedantic then be pedantic
about variable and method names. As a general rule, try to make the
method names contain verbs (getNumberOfRecords()) and variables nouns
(numberOfRecords). Variable names shouldn't reflect the type a-la MS
or Polish notation. It can change and having the type in the var name
doesn't help much.
One rule I learned is "if you want to write a comment to explain the
next block of code then put it in a method and give it a descriptive
name". The idea is that today's compilers are smart enough to inline
and optimize method calls so your performance shouldn't suffer while
your code will be much more readable and it helps with another rule of
thumb - "never have a method longer than your monitor" - so you can
have a view of the entire method without too much scrolling back and
forth.
On the other hand, having the scope prefix for variable names helps a
lot ("m" for class member, "c" for constant, "s" for static class
member, "g" for, god forbidden, global variable. No prefix for local
automatic variables). So "mRecordCount" tells you that this is a
per-instance class member while an "sInstanceCount" tells you this is
a class static variable.
How do you get to such code? Top-down programming. Start with "main"
then tell yourself "what is the program going to do? It's going to
read command line parameters, verify the environment is not missing
anything vital, run the main function, then exit":
main(int argc, const char **argv)
{
parseCommandLineArgument(argc, argv);
checkEnvironmentAndExitIfBad();
runMainFunction();
exitWithStatus();
}
void parseCommandLineArgument(int argc, const char **argv)
{
}
void checkEnvironmentAndExitIfBad()
{
}
void runMainFunction()
{
}
void exitWithStatus()
{
}
The above should be compilable (give or take).
Then break down the above mentioned methods and so on.
Cheers,
--Amos
--
SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/
Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
On Monday 12 January 2009 20:18:39 slug-requ...@slug.org.au wrote: > A quick set of three basic guidelines for comments. I find these get > my through most situations. > > 1. The code says what you are doing, the comments say WHY you are doing it. > > 2. The code is there to teach people who aren't you (which includes > you-in-12-months) about the code, so in general they should be before > a block of code, and introduce it. > > 3. Comments are for humans. Don't leave commented out old code around, > they just mess up the comments, and you should be using version > control for that anyway. These are the utterly most important points, and are so very often ignored. Read them 3 or 4 times and never waver. You write the code After 3 months you are amazed at how badly you commented it After 12 months it looks like someone else's code James -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Thanks Adam and Michael, that was exactly what I was after. I sort of thought about that line but was not sure. Cheers, seb Adam Kennedy wrote: > A quick set of three basic guidelines for comments. I find these get > my through most situations. > > 1. The code says what you are doing, the comments say WHY you are doing it. > > 2. The code is there to teach people who aren't you (which includes > you-in-12-months) about the code, so in general they should be before > a block of code, and introduce it. > > 3. Comments are for humans. Don't leave commented out old code around, > they just mess up the comments, and you should be using version > control for that anyway. > > Adam K > > 2009/1/12 Sebastian : > Hi all, > > 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? > > 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. > > 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... > > 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. > > > Cheers, > > seb > - -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html >> -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAklrJmQACgkQMuBzgG5z7F/i9QCfVj0wlMswpTGHDv8F8U9BORh1 zOsAoL/qFYi9xZH3Hd7BjeWl+KB0ccIf =geNm -END PGP SIGNATURE- -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
On Monday 12 January 2009 12:21:09 Daniel Pittman wrote: 8x< > 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. />x8 Well said. (As also your other notes.) I would just add: Use function header documentation! Find a template that suits you and stick to it like glue. Too many times I have caught myself out six months later trying to figure out what the heck the rationale, result and parameters for "this" function are. I mean, I must have put this code into a function for some reason, usually re-useabilty, and usually when I think "I think I've got a routine for that somewhere", I usually also think " I hope-to-dog that I documented it". And finally, dont forget the power of //hack and //todo! hth bruce -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
hi, On Mon, Jan 12, 2009 at 11:17 AM, Sebastian wrote: > -BEGIN PGP SIGNED MESSAGE- > Hash: SHA1 > > Hi all, > > 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? i agree with the replies to this thread already. the only thing i'd add as advice to a new programmer - try to avoid the need for comments by making the code as human-readable as possible. yeah, this may seem like not quite what you were asking, but i think its part of the same problem. so: - try to make variable names, function names, etc, as meaninful as possible within the constraints of the language and keystroke-sanity - whenever possible, avoid magic numbers/strings, and define a variable/constant with a meaningful name cheers justin -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
A quick set of three basic guidelines for comments. I find these get my through most situations. 1. The code says what you are doing, the comments say WHY you are doing it. 2. The code is there to teach people who aren't you (which includes you-in-12-months) about the code, so in general they should be before a block of code, and introduce it. 3. Comments are for humans. Don't leave commented out old code around, they just mess up the comments, and you should be using version control for that anyway. Adam K 2009/1/12 Sebastian : > -BEGIN PGP SIGNED MESSAGE- > Hash: SHA1 > > Hi all, > > 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? > > 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. > > 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... > > 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. > > > Cheers, > > seb > > -BEGIN PGP SIGNATURE- > Version: GnuPG v1.4.7 (MingW32) > Comment: http://getfiregpg.org > > iD8DBQFJaowNMuBzgG5z7F8RAqZoAJ9Pzw3SRaes6LOdlU4bOqCQSZPFVACghmIG > NhFonZutl3aBKUneNvtlDOE= > =fJ7n > -END PGP SIGNATURE- > -- > SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ > Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html > -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
On Mon, Jan 12, 2009 at 10:47 AM, Sebastian wrote: > Hi all, > > 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? Depends upon the programming/software engineering community you're working in. Some people are very anti-comments, others see it as a mandatory. Follow the conventions around you. The key point is that if you do comment, make them worthwhile. Don't just paraphase the code but explain what's going on. i.e. # Increment x by 1 x = x + 1; is most certainly a waste of everyone's time, but // Calculate the Levenshtein distance between s1 and s2 // refer http://www.merriampark.com/ld.htm#REFS for details. Explains WHAT you're doing, but not HOW you're doing it. You can read the code for the 'how' (although if you're doing something tricky or deviating from a well-known algorithm then that's when explaining the 'how' adds value) i.e. // Calculate the Levenshtein distance between s1 and s2 // refer http://www.merriampark.com/ld.htm#REFS for details. // Note that the inner loop is deviates from the norm since // we're only handling strings less than 5 chars. > 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. 'Before' is the typical convention. Although an end of line comment can be useful if not too long. > 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... > > 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. As per coding standards in general follow the conventions of the existing code. If this is new code, it's up to you, but the usual advice is to follow the conventions of the language or community you're targeting. That way you'll attract others, and it'll be easier to keep it consistent going forward. If the code is only for your eyes, remember the goal is still to be able to come back and change that code in 6 months time. Note that some communities, such as Python and the Linux Kernel (to name two) have very strong existing coding standards. "Always code as if the person who'll be maintaining your code is a violent psychopath who knows where you live" is something to remember when you're trying to decide whether you need to comment a piece of code :-) Hope this helps, -- Michael Davies "Do what you think is interesting, do something that mich...@the-davies.netyou think is fun and worthwhile, because otherwise http://michaeldavies.org you won't do it well anyway." -- Brian Kernighan -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
Re: [SLUG] comments in scripts and source code
Sebastian 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
[SLUG] comments in scripts and source code
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi all, 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? 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. 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... 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. Cheers, seb -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.7 (MingW32) Comment: http://getfiregpg.org iD8DBQFJaowNMuBzgG5z7F8RAqZoAJ9Pzw3SRaes6LOdlU4bOqCQSZPFVACghmIG NhFonZutl3aBKUneNvtlDOE= =fJ7n -END PGP SIGNATURE- -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
