[ Date Index ] [ Thread Index ] [ <= Previous by date / thread ] [ Next by date / thread => ]
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