写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%."