On Mon, Jan 12, 2009 at 10:47 AM, Sebastian <[email protected]> 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. <insert code here> 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. <insert code here> > 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 [email protected] you 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
