D&C GLug - Home Page

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

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

 

On Tuesday 12 August 2008 12:57, Grant Sewell wrote:
...

> 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 didn't say 'no comments' I said comments aimed at someone who was going to 
maintain the code. I don't see why every piece of code I write should be a 
tutorial about whatever language I'm writing in - theres better places and 
better people than me to write that sort of thing. I've read 'mature' code 
with comments that have explained things fully only to discover this code is 
never ever compiled let alone run.
Comments should be necessary and sufficient - no more. A lot of the time the 
best explanation will be in the docs associated with the code - the spec, the 
'api' descriptions, UML diagrams etc.
And if you really want to learn what the code is going to do step though it in 
a debugger. Mind you I've tried that on GCC....
I'm a great believer in avoiding redundancy wherever possible - this actually 
minimises work in the long term. In c/c++ all you should need to know from a 
user point of view should be in the header files. If theres something really 
obscure in the code - or seventeen levels of dereferencing or some neat trick 
that speeds things up expand on that. But please don't explain loops in 
english as so many do - you just double the work needed to maintain it and 
make it harder for someone to learn when comments/code get out of step.
If your writing a project in an IDE or something then the best place for 
describing whats going on is in the project somewhere and not the code. 
Templates and factories anyone: This thingy takes a thingA and does thingB  
with it? Clear as mud, or very verbose when you take the product of the 
variables and explain those individually.
Explaining usage/function in the code is often meaningless or verbose and 
makes maintenance a lot more difficult //see I'm repeating myself here - 
should have used a pointer!
The only time (if(inclined){goto Caveat;}) I've thought comments might really 
be useful and not anal is in unit tests where theres some context to provide 
real meaning and understanding. 
Code never is, and never should be though of as being isolated and self 
contained. 
try{
//A writer (Fitzgerald)  once wrote that a man doesn't exist until he's drunk. 
        //Code doesn't exist until its exercised. 
}Catch(MixedMetaphore *e){
//I'm talking rubbish here but this comment wont help!!!
throw(paddy(e));//get upset because life is too difficult and if I could 
explain what I was doing I'd be an author and not a badly paid coder working 
for fools.
}
finally{//go to the pub - must be run every day
HaveDrink();/*is that an object, a method or a spelling mistake? see coding 
standards manual...perhaps I should append that here to make it clearer...*/
}

Caveat:
I personally would like to see a development arrangement that recognises the 
orthogonal  separation of human description from code while allowing them to 
be linked and cross checked - you hover over the code in the editor or 
debugger and are allowed to see/edit/modify/generate template  comments. This 
will make it a lot easier for internationalisation. Has it ever occurred to 
you that your comments may be read by foreigners and so should be in 
UPPERCASE.

Tom te tom te tom



-- 
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