D&C GLug - Home Page

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

Re: [LUG] Linux @ University of Plymouth

 

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.
> .
>
> My main aim for uni, apart from the social aspect is to get some peer
> review on my work, as it were. I've self taught up till now, and while I
> try my best to follow conventions, standards and program design it is still
> all self taught and neither myself, nor the internet and books are
> infallible so it will be good to see what I don't know and were I'm weak.
I get the feeling your college peers and uni lecturers might not be able to 
tell you!


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