Self Documenting Code是否重要？

写Self Documenting Code很重要；这里有一个不错的帖子，它的讨论更好，有兴趣的朋友可以看看。

原帖：

  http://progfu.com/post/2668280164/your-code-is-not-self-documenting

 

讨论精华：

The people who have commented disagreeing with you are clearly inexperienced

developers who have never had to come back and maintain a project six months

later, and have never had to take over someone else's project after they have

left. Do these people think they never leave bugs in their code? Without comments

you cannot tell the real intention of code that has a bug in it. And without

comments you cannot understand how the code is meant to fit into the rest of the

project. A good comment explains the reasoning behind the code. Why is it doing

this? What are the assumptions and limitations? Professional software development

means good design, good documentation and good code.






In my opinion saying WHAT the code does is less important than saying WHY it does

it. This is a shorter way of saying what Paul said just now.

It is usually obvious what the code does (though finding where it does it can be

a pain) but harder to figure out why it is there.

Which is why one of my rules is a paragraph at the top of each class detailing

responsibilities and context in the wider codebase.
Normally this does not change as the code evolves.





Completely disagree with this. When push comes to shove, documentation and code

*alway* diverge. The kind of information you're talking about is either

inadequate to answer the questions someone is going to have or will be detailed

enough that it will need maintenance. And since there is no way to guarantee that

the documentation and code will match, people will have to read the source

anyhow.

Write better tests. Tests should have good names that contain the same

information that your comment should, should have a point that is made clearly so

that they can be understood at a glance, and should have assertions that back up

that point clearly. The advantage is that tests *always* match the code.

The cost is that you have to treat your tests as you would documentation and

optimize their content for readability over most other concerns.






Personally, I like writing the comments of a unit of code first (before writing

any code), just to check the logic of my intention. If it makes sense to me after

writing the comments, then my final implementation will usually work as intended.

This is a form of pseudocode / simulation testing prior to coding that works for

me. YMMV

One of the features of this method is that if you are subject to frequent

interruptions, the comments can help restore your train of thought much faster

than without them.

Last thought: Comments of Why are essential long-term project documentation,

Comments of How primarily assist testing and bug-finding, and are more prone to

maintenance errors.

If you comment (how) before you write the code, and update the comments before

you change the code, the problem of out-of-date comments should be greatly

reduced.




I agree that commenting your code is a must. But commenting the "WHY" and not the

"WHAT" is more appropriate. The code itself tells the what, but we cannot always

determine the intent of the author. Also, if you are building API docs, you've

got to have comments - what, why, and how.





Code can actually be self-documenting, but not self-commenting.

Also, your rant isn't about documentation, but commenting (documentation!

=comments).

Trust me, I've had cases where each line of code was proceeded with 2-5 lines of

comments, and they didn't help one bit explaining what the all code was actually

doing.

So not only "less is more", but "quality over frequency" as well.




of course the real question isn't how fast programmers type, it's how fast they

delete...

Self commenting code is nothing to do with external documentation. Documentation

is to describe the general outline/design of the system, the code is to describe

the system implementation. The more comments you put it, the more things you need

to maintain and to look at.

would your backup code look better like this:
void Backup()
{
//Backup database
... lots of code

//Backup repositories
... lots of code
}

Why have comments there, again, this has nothing to do with documentation, it's

to do with implementation.

Code without properly grained documentation is not maintainable, code with too

many comments is not maintainable, code with no tests is not maintainable.

Good clean code, with good clean naming conventions, and unit/integration tests

is well, you get my drift...

Again, it's not about how much you write, it's about how much you can remove...




Documenting code well is a learned discipline and, like all aspects of writing

software, requires judgement. Most often what needs to be documented is why

something is being done or why it is important. Just ask yourself what comments

would be helpful two years from now if you have to revisit the code. More than

anything, good documentation reduces the time it takes to understand code.


Obviously no programming language is perfect, and that's why self-documenting

code is impossible to always acheive, but the more the better!




I agree totally. "Self documenting code" is much faster and easier to read, but

it isn't the end of the story: it doesn't explain how to use a method/class, what

order a related sequence of calls must be made in, whether a parameter can be

null, what return code is given to mean 'not found', etc. And with modern IDEs

any additional documentation can be shown live as you type to confirm all the

details you need, so you don't have to find and read the source to understand how

to use it.



Completely agree with you especially when I come back to my own uncommented code

and have to figure out exactly what I was thinking...




I would never argue that documentation isn't important, but most of the time, you

aren't working in an ideal scenario (e.g. when you have enough time to do

everything right). How to resolve the need to get a job done, while minimizing

the risk of leaving behind badly documented code that will cost you (or someone

else) a lot of time in the future?




I've come to change my opinion after discovering two things: experienced

programmers _are_ able to write properly self-documenting code, and the statement

"debug only code. comments can lie"


Good naming can explain a lot of things, but it doesn't explain what happens when

you pass wrong parameter, eg. you pass already closed socket instead of open one,

or empty array ... or when the method throws exceptions.





Not all languages force you to define the types of parameters or return value. A

simple thing such as Array.index(0) — without documentation, what would could you

possibly expect it to return? null? false? raise exception? default value? the

array itself?

If you change code, you change the documentation. If you test your code, you

should test your documentation.



If there is any doubt about what will happen in a special case, it should be

documented, because otherwise you can only figure it out manually or digg into

the source code.

 

 

 

 

 

 

 

 

 

 

另外有一个关于better code的帖子，也一并给出。

 

http://progfu.com/post/384161195/11-tips-for-better-code#

 

 

I don't have any hard rule here, but I'd say most should not be more than 100 lines. Setting hard limits is for inexperienced people who have no idea what is going on and causes people to write code to match the rules rather than follow a logical flow. Extremely short methods leads to method spam and spaghetti-zed code. If you think having to scroll down a bit to read a method is bad, try jumping to a completely new class or another method hundreds of lines down. Trying to keep track of what is happening (state) through chained method calls is extremely frustrating. I'm not promoting the use of giant methods, but rather just like class design, do what makes logical sense.

 

If we adhere to the SRP, both at the class level and at the method level, then
* we "Keep methods short"
* we have a chance to choose method names that follow "Use self-descriptive variable and method names".
* we inevitably "Define variables as close as possible to the place of their first usage"
* we "Never ever ever reuse a variable for different purpose"

 

A summary principle extracted from this is: Code is about communication and all these points lead to letting another programmer understand your code better even in furture.

 

 

I agree with them all in principle
In particular number 1 "keep the entire method on screen". I reckon this is very important for readability. Though code complete points out that long methods don't necessarily lead to more bugs.

 

#1: I dont believe you can make number a hard and fast rule. The concept is right, tho.

#9: Definately disagree: you want refractoring (i.e good programming practices) to become second nature. Leaving everything up to unit tests invites lazy programming, especially in larger projects.

 

 

one more.

Get 5 lines of code to work before 50. Many a time I've been brought non-functioning code with the plea, "Help me." Usually I end up gutting the code down to the bare minimum to get it to work and then add on the bells and whistles and error handling.

 

they're more of a guidelines than rules that must be obeyed 110% of the time.

 

 

From my experience, it's almost always bad when you optimize by guessing, but optimizing based on hard evidence isn't a bad practice.

 

 

"Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%."