Click here to Skip to main content
12,506,574 members (55,946 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, embarrassing 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: ... WHY?! Pin
Matt U.22-Nov-13 3:38
memberMatt U.22-Nov-13 3:38 
JokeRe: ... WHY?! Pin
walterhevedeich25-Nov-13 22:54
memberwalterhevedeich25-Nov-13 22:54 
GeneralRe: ... WHY?! Pin
Bernhard Hiller25-Nov-13 23:35
professionalBernhard Hiller25-Nov-13 23:35 
GeneralRe: ... WHY?! Pin
Giuseppe Tollini21-Nov-13 9:33
memberGiuseppe Tollini21-Nov-13 9:33 
GeneralRe: ... WHY?! Pin
Matt U.21-Nov-13 10:03
memberMatt U.21-Nov-13 10:03 
GeneralOver-documentation Pin
Ron Beyer16-Nov-13 14:46
professionalRon Beyer16-Nov-13 14:46 
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 
GeneralRe: VS Go BOOM! Pin
DaveAuld15-Nov-13 20:38
protectorDaveAuld15-Nov-13 20:38 
GeneralRe: VS Go BOOM! Pin
devvvy16-Nov-13 22:51
memberdevvvy16-Nov-13 22:51 
GeneralRe: VS Go BOOM! Pin
Im_no_troll18-Dec-13 10:19
memberIm_no_troll18-Dec-13 10:19 
GeneralRe: VS Go BOOM! Pin
Jacek Gajek27-Dec-13 1:13
memberJacek Gajek27-Dec-13 1:13 
GeneralRe: VS Go BOOM! Pin
Sander Rossel17-Nov-13 0:10
memberSander Rossel17-Nov-13 0:10 
GeneralRe: VS Go BOOM! Pin
Jacek Gajek27-Dec-13 1:16
memberJacek Gajek27-Dec-13 1:16 
GeneralDetect user in group only once Pin
SortaCore15-Nov-13 0:15
memberSortaCore15-Nov-13 0:15 
GeneralRe: Detect user in group only once Pin
Jacek Gajek15-Nov-13 0:31
memberJacek Gajek15-Nov-13 0:31 
GeneralRe: Detect user in group only once Pin
SortaCore15-Nov-13 0:32
memberSortaCore15-Nov-13 0:32 
GeneralRe: Detect user in group only once Pin
Jacek Gajek15-Nov-13 0:43
memberJacek Gajek15-Nov-13 0:43 
GeneralRe: Detect user in group only once Pin
SortaCore15-Nov-13 0:53
memberSortaCore15-Nov-13 0:53 
GeneralRe: Detect user in group only once Pin
PIEBALDconsult15-Nov-13 2:57
professionalPIEBALDconsult15-Nov-13 2:57 
GeneralRe: Detect user in group only once Pin
Marc Clifton17-Nov-13 4:38
protectorMarc Clifton17-Nov-13 4:38 
GeneralWhat is an Object Pin
michaelbarb14-Nov-13 8:44
professionalmichaelbarb14-Nov-13 8:44 
GeneralRe: What is an Object Pin
DaveAuld14-Nov-13 9:00
protectorDaveAuld14-Nov-13 9:00 
GeneralRe: What is an Object Pin
michaelbarb14-Nov-13 9:16
professionalmichaelbarb14-Nov-13 9:16 
GeneralRe: What is an Object Pin
Joan Murt14-Nov-13 9:10
professionalJoan Murt14-Nov-13 9:10 
GeneralRe: What is an Object Pin
Richard Deeming14-Nov-13 9:17
professionalRichard Deeming14-Nov-13 9:17 
GeneralRe: What is an Object Pin
Freak3014-Nov-13 22:02
memberFreak3014-Nov-13 22:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    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
Web02 | 2.8.160927.1 | Last Updated 28 Sep 2016
Copyright © CodeProject, 1999-2016
All Rights Reserved. Terms of Service
Layout: fixed | fluid