D&C GLug - Home Page

[ Date Index ] [ Thread Index ] [ <= Previous by date / thread ] [ Next by date / thread => ]

[LUG] Code comments (was Linux @ University of Plymouth)

 

Tom Potts wrote:
> On Tuesday 12 August 2008 11:09, Ross Bearman wrote:
> ...
>   
>> Personally I'm a big fan of minimalistic commenting in my programming;
>> coding as if comments didn't exist, and only adding comments in when
>> something needs explanation, rather than commenting every line, a good
>> article on it can be found on Coding
>> Horror<http://www.codinghorror.com/blog/archives/001150.html>
>>     
> You will find a lot of companies have documentation standards that insist you 
> try and explain the bleeding obvious to someone who wouldn't get it if they 
> had a gun pointed to their head. 
> You don't write comments for managers - you write comments for people who may 
> need to maintain the code: Programmers! Some of whom know what a pointer is!
> The only comments should be 'hyperlinks' to the part of the spec the code was 
> built on. If its evolutionary code - ie you're just winging it then the 
> comments are for yourself (and pair) and will dissappear in version 1.0 after 
> refactoring. Brief method descriptions are cool - /** stuff for JavaDoc seems 
> cool until the spec changes a bit.... Horses for Courses: separate 
> functionality from style, code from documentation, coders from managers.
> If you have to explain anything your probably trying to be a bit too smart - 
> or writing machine code where comments are genuinely useful.
>   
That all depends on what your purpose of reading the source code is!  I 
doubt even the smartest of coders was born with that talent - it was 
learnt.  Reading through books and guides can only get you so far with 
learning a programming language.  Obviously you should strike out with 
your own ideas when learning a new language, but reading through (and 
modifying) other's code is also fun... if there are no comments at all, 
you may have no idea what's going on at all.

I'm not saying that you should write "carefully formatted epic poems 
every second line of code" (from the link, above), but having none can 
be equally as bad... IMO.

Grant.

-- 
The Mailing List for the Devon & Cornwall LUG
http://mailman.dclug.org.uk/listinfo/list
FAQ: http://www.dcglug.org.uk/linux_adm/list-faq.html