The hardest part about programming is...

1 day ago, JoshRoss wrote

 

*snip*

For the most part, programmers write poor documentation. Do you think having Microsoft provide a certification for documentation, would improve the situation?

-Josh

 

 

Have you read some of the MSDN documents?

No I don't think that would help all that much...

My code documents itself

1 minute ago, Maddus Mattus wrote

My code documents itself

My code obfuscates itself

I document my code, but I also try to create classes that are inuitive representations of the object of what they do...  a lot of the third party libraries I find are really difficult to figure out just because they try to find the cleverest way to do something instead of the most intuitive way to do it.

11 hours ago, harlock123 wrote

*snip*

Have you read some of the MSDN documents?

No I don't think that would help all that much...

You hit the nail on the head with that one. I think the problem lies with automatic generated documentation. If it wasn't automatically generated, then I guess someone would have to actually write something about what all these classes are for and what the methods do.

I wonder if the content would be better if people had to pay for it. Surely, Jaron Lanier would have something to say about that.

-Josh

Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

@Bass: Sometimes I create ridiculously long method names, and later shorten them, and put in a comment, for the sake of brevity. The stupid thing about that is the simpler the function, the more outrageous the name.

-Josh

@harlock123: Comparitively speaking (to other libraries from other companies), the MSDN docs are pretty good, especially considering how much stuff there is to document. 

1 hour ago, Bass wrote

Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

I'll bet the guy who wrote the 10 year old C++ code I am debugging for memory leaks thought it was obvious what he was thinking, when he wrote it.  Alas, no documentation *at all*.  A whole load of low level memory manipulation to fit into one can only presume was 640K of memory ... <sigh>.

4 hours ago, Bass wrote

Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

I've always found people who don't like to comment their code also don't like to test their code and rarely like to use anyone else's code. It's obvious isn't it?

I guess I don't own an iPhone...

Programming for the sake of getting something visual for decision makers to wrap their heads around only to find out they like it as is and now we have to support it for 10 years.

I just finished reading Code Complete and the general practice promoted was to comment

1) code blocks (maybe.  And if you do, don't just repeat the code, describe what it does.)

2) methods and parameters

3) Anything that isn't extremely clear

@ScanIAm:I find it helpful if you comment with more than just the what, but also the why.

@kettch:

Oh yeah. A lot of times someone comes in and just break it because they didn't know WHY. Althought usually a good Unit Testing can prevent that.

I usually comment block by block to explain the purpose of each block. So I would know a general implementation flow of a particular method.

1 day ago, Richard.Hein wrote

*snip*

I'll bet the guy who wrote the 10 year old C++ code I am debugging for memory leaks thought it was obvious what he was thinking, when he wrote it.  Alas, no documentation *at all*.  A whole load of low level memory manipulation to fit into one can only presume was 640K of memory ... <sigh>.

Well you are debugging poorly written code. If the code you are reading is hard to understand, that's the code's problem. I stick to what I said: clean code doesn't need (and shouldn't have) comments. Why? Because clean code is ALWAYS understandable in it's own right.

@Bass:

Define "Clean Code".

I did a simple loop of for(int i=1; i<n; i++) and there is an important reason why I do it from 1 instead of 0. No comment will make someone else think it should start from 0. They will change it and break it.

57 minutes ago, Bass wrote

*snip*

Well you are debugging poorly written code. If the code you are reading is hard to understand, that's the code's problem. I stick to what I said: clean code doesn't need (and shouldn't have) comments. Why? Because clean code is ALWAYS understandable in it's own right.

Yes.  All one must do is put oneself into the exact mindset of the original coder and enlightenment will occur.  And all projects are of a size that allows a single developer to keep track of all business logic and esoterica within their own head.  And people always interpret names the same way.  And we all speak english.

Seriously?!?