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)

 

I always found, and this might just me, but code explanations written
as closely to pseudo code make a lot more sense. Definitely not just
psuedo code, but I tend to try and be simplistic and black and white
in most of my comments. When I'm reading other people code, I find it
jarring when somebody who is clearly a good coder, but not so much a
good writer, trying to explain a complex procedure using
conversational language. When trying to explain a binary process, it's
much simpler to explain it in simple terms as the computer sees it,
rather than trying to bend the English language to your will.

Regards, Ross Bearman



On Tue, Aug 12, 2008 at 3:26 PM, Tom Potts
<tompotts@xxxxxxxxxxxxxxxxxxxx> wrote:
> 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
>

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