Click here to Skip to main content

The Weird and The Wonderful

   

The Weird and The Wonderful forum is a place to post Coding Horrors, Worst Practices, and the occasional flash of brilliance.

We all come across code that simply boggles the mind. Lazy kludges, embarrasing mistakes, horrid workarounds and developers just not quite getting it. And then somedays we come across - or write - the truly sublime.

Post your Best, your worst, and your most interesting. But please - no programming questions . This forum is purely for amusement and discussions on code snippets. All actual programming questions will be removed.

 
GeneralRe: Over-documentation PinprofessionalPIEBALDconsult16-Nov-13 15:15 
GeneralRe: Over-documentation PinprotectorOriginalGriff16-Nov-13 22:20 
GeneralRe: Over-documentation PinprofessionalPIEBALDconsult17-Nov-13 5:26 
GeneralRe: Over-documentation PinprotectorOriginalGriff17-Nov-13 5:42 
GeneralRe: Over-documentation PinmemberMax Methot28-Nov-13 5:01 
GeneralRe: Over-documentation PinprofessionalPIEBALDconsult28-Nov-13 5:45 
GeneralRe: Over-documentation PinmemberSander Rossel17-Nov-13 0:09 
GeneralRe: Over-documentation PinprofessionalRon Beyer17-Nov-13 5:21 
I would say if the people working on your code can't put the caret in the middle of "string" (or whatever you are using) and hit F1 to read the MSDN documentation, they probably shouldn't be messing around in the code base.
 
There are a lot of theories about how to document code, and here's mine:
 
1. Classes, methods, and properties (public especially, but all really), should be documented using the built-in /// method, with at least the summary and parameter explanations, remarks should be added if there is more, and document the exceptions that the method throws. This makes the other developers life easier (in Intellisense and later when you generate API documentation) to understand what a class/method/property is for.
 
2. Internal documentation (inside methods), generally skip it. There are three (main) reasons why somebody would document inside a function, (a) its complicated or (b) its long. If either of these are the case, it should be refactored. If the purpose of the function is sufficiently documented and the developer is qualified to work on it, the interior doesn't need to be documented. (There are of course rare exceptions, such as documenting bug work-arounds which if the developer didn't have knowledge of the bug, the code wouldn't make sense). The other reason (c) why people put comments in functions is generally white-noise. They are documenting the thought process which is unnecessary. A proper description of the input/output of the function and it being correctly "factored" shouldn't require knowing the developers thought process as they wrote it. When you see that they are probably doing "design by code", or "code-first", I won't get into that...
 
I used to be in the school of "every line should be documented", but I learned that really the comments where only there for the sake of writing the code, when I was debugging it I never looked at the comments again. It was more of "thinking out loud" than anything. Since adopting my method, I write cleaner, less cluttered code...
GeneralRe: Over-documentation PinmemberSander Rossel17-Nov-13 6:54 
GeneralRe: Over-documentation [modified] PinmemberENOTTY18-Nov-13 5:24 
GeneralRe: Over-documentation PinprofessionalRon Beyer18-Nov-13 5:41 
GeneralRe: Over-documentation Pinmember d@nish 17-Nov-13 6:20 
GeneralRe: Over-documentation PinprofessionalRon Beyer17-Nov-13 6:55 
GeneralRe: Over-documentation PinprofessionalBernhard Hiller17-Nov-13 23:01 
GeneralRe: Over-documentation PinmemberENOTTY18-Nov-13 5:05 
GeneralRe: Over-documentation PinmvpCPallini18-Nov-13 7:39 
GeneralRe: Over-documentation PinprotectorMarc Clifton19-Nov-13 8:24 
GeneralRe: Over-documentation PinmemberStewart Judson20-Nov-13 0:49 
GeneralRe: Over-documentation PinprofessionalRon Beyer20-Nov-13 3:08 
GeneralRe: Over-documentation Pinmembers_mon25-Nov-13 9:56 
GeneralRe: Over-documentation PinmemberRob Grainger28-Nov-13 22:26 
GeneralRe: Over-documentation PinmemberVasudevan Deepak Kumar29-Nov-13 1:54 
GeneralAbsolutely necessary Pinmemberimagiro15-Dec-13 23:00 
GeneralRe: Over-documentation PinmemberJacek Gajek27-Dec-13 1:05 
GeneralVS Go BOOM! PinprofessionalBrisingr Aerowing15-Nov-13 12:54 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.


Advertise | Privacy | Mobile
Web01 | 2.8.140415.2 | Last Updated 17 Apr 2014
Copyright © CodeProject, 1999-2014
All Rights Reserved. Terms of Use
Layout: fixed | fluid