Click here to Skip to main content
11,636,889 members (73,958 online)

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 Pin
PIEBALDconsult16-Nov-13 15:15
professionalPIEBALDconsult16-Nov-13 15:15 
GeneralRe: Over-documentation Pin
OriginalGriff16-Nov-13 22:20
protectorOriginalGriff16-Nov-13 22:20 
GeneralRe: Over-documentation Pin
PIEBALDconsult17-Nov-13 5:26
professionalPIEBALDconsult17-Nov-13 5:26 
GeneralRe: Over-documentation Pin
OriginalGriff17-Nov-13 5:42
protectorOriginalGriff17-Nov-13 5:42 
GeneralRe: Over-documentation Pin
Max Methot28-Nov-13 5:01
memberMax Methot28-Nov-13 5:01 
GeneralRe: Over-documentation Pin
PIEBALDconsult28-Nov-13 5:45
professionalPIEBALDconsult28-Nov-13 5:45 
GeneralRe: Over-documentation Pin
Sander Rossel17-Nov-13 0:09
memberSander Rossel17-Nov-13 0:09 
GeneralRe: Over-documentation Pin
Ron Beyer17-Nov-13 5:21
professionalRon 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 Pin
Sander Rossel17-Nov-13 6:54
memberSander Rossel17-Nov-13 6:54 
GeneralRe: Over-documentation Pin
ENOTTY18-Nov-13 5:24
memberENOTTY18-Nov-13 5:24 
GeneralRe: Over-documentation Pin
Ron Beyer18-Nov-13 5:41
professionalRon Beyer18-Nov-13 5:41 
GeneralRe: Over-documentation Pin
d@nish 17-Nov-13 6:20
member d@nish 17-Nov-13 6:20 
GeneralRe: Over-documentation Pin
Ron Beyer17-Nov-13 6:55
professionalRon Beyer17-Nov-13 6:55 
GeneralRe: Over-documentation Pin
Bernhard Hiller17-Nov-13 23:01
professionalBernhard Hiller17-Nov-13 23:01 
GeneralRe: Over-documentation Pin
ENOTTY18-Nov-13 5:05
memberENOTTY18-Nov-13 5:05 
GeneralRe: Over-documentation Pin
CPallini18-Nov-13 7:39
mvpCPallini18-Nov-13 7:39 
GeneralRe: Over-documentation Pin
Marc Clifton19-Nov-13 8:24
protectorMarc Clifton19-Nov-13 8:24 
GeneralRe: Over-documentation Pin
Stewart Judson20-Nov-13 0:49
memberStewart Judson20-Nov-13 0:49 
GeneralRe: Over-documentation Pin
Ron Beyer20-Nov-13 3:08
professionalRon Beyer20-Nov-13 3:08 
GeneralRe: Over-documentation Pin
s_mon25-Nov-13 9:56
members_mon25-Nov-13 9:56 
GeneralRe: Over-documentation Pin
Rob Grainger28-Nov-13 22:26
memberRob Grainger28-Nov-13 22:26 
GeneralRe: Over-documentation Pin
Vasudevan Deepak Kumar29-Nov-13 1:54
memberVasudevan Deepak Kumar29-Nov-13 1:54 
GeneralAbsolutely necessary Pin
imagiro15-Dec-13 23:00
memberimagiro15-Dec-13 23:00 
GeneralRe: Over-documentation Pin
Jacek Gajek27-Dec-13 1:05
memberJacek Gajek27-Dec-13 1:05 
GeneralVS Go BOOM! Pin
Brisingr Aerowing15-Nov-13 12:54
professionalBrisingr 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
Web04 | 2.8.150728.1 | Last Updated 30 Jul 2015
Copyright © CodeProject, 1999-2015
All Rights Reserved. Terms of Service
Layout: fixed | fluid