Every comment there disagrees with the post. Were you hoping to come here and find people who will agree?
I also disagree with it. Good code is as self-documenting as possible. Any gotchas should be explained in comments, but correct naming is way more valuable than comments explaining what a function does.
Any code that fails to be self-documenting needs to be refactored immediately.
To follow the ongoing culture of disagreeing, I disagree with you that bad code needs to be refactored immediately.
That has a technical reason: "Don't touch a running system." You know, you can never be sure what you change there, if the code is really that bad.
And it also has a management reason: Everything these days is about efficiency. You only have a limited amount of resources. That might be coders in your company, when you are the CEO. That might be free time, when you code for yourself. But all these resources should be spent wisely. So, if refactoring the code takes a lot of resources and the functionality of the software actually stays the same, I would suggest to do that later, when it really needs to be done because you need to change the functionality. And if it is selfwritten code, it might be smart to go on with the next project and improve your coding quality through more experience over time and maybe later come back to refactor.
> That has a technical reason: "Don't touch a running system." You know, you can never be sure what you change there, if the code is really that bad.
My experience has been that "Don't touch a running system." takes you to "How the heck does this thing work?". And every time even little fixes get hairy and time-consuming. It's kind of when you listen to people justifying their untidiness: they say they do know where to look for things. Yes, they do know, I'm sure, but can they find those things quickly, especially when "the shit hits the fan"? Does their approach work when their lives get more complex? How would they score against people who keeps things sorted and plan ahead? I have been a pretty untidy teenager, using these very same lame excuses, but nowadays I can't afford it.
Your conclusions are soooo right. Really. It is exactly the same thing as tidyness in your room.
Where does this tidyness come from? It doesn't come from often cleaning up the shit you made, hopefully before it hits any fans. For most people it comes from having an order of things in your shelves and teaching yourself to not drop everything you hold in your hand just where you don't need it anymore, but put it back in the place where it belongs.
My argument is that - and that is where I can be right or wrong - you write good or bad code because you have the skill to do so. And also that you write good or bad code because you have an order for things and a (somewhat engineeringly/scientifical) process of writing code, that the readability in your code does not come from saying "I make it clean now" but from the sum of all the small steps that produce the least amount of shit as a sideeffect.
The thing is, if you have ugly code that is not easy to understand, the author didn't really understand the problem and the solution either. It was more the magician approach, where you put in many things together and suddenly it works approxamitally how the author has planned (probably there are also no good designed structure documents and unit tests in such a case). And then he just said "okay, now it's finished." If you come and "refactor" it, it is actually that YOU will be the one who solves the real problem the first(!) time, because the ugly code obviously doesn't solve any problem well enough (otherwise, where does the bug reports come from that are so hard to solve).
Okay, that is that. But from your argument, lelele, I wonder, if my secon point was also unclear. I meant that you should of course handle the mess, but WHEN IT IS ABSOLUTELY NESSESARY. If you don't need to, if you can live with the mess in this moment right now and if the problems (bugs etc.) are not that bad (e.g. don't need to be fixed at the moment, because there are bigger things to do), then don't solve the problem NOW. BUT ALSO when the time comes and you have a bug, that really needs to be fixed you should take the time and energy and really clean up the code first. In my small experience (2 years are not enough to be really sure yet) a good process is the following:
1. you discover a problem (through bug reports, dying servers, a screaming boss running your way, you-name-it)
2. you define and evaluate the problem (Is it a problem? Do I(!) need to solve it? Is it worth the time I will spent on it? etc.)
3. you write unit tests to keep the actual thing that the program does without changes and find the place in the code where the bug occurs.
4. now that you can not destroy functionality you plan how to change the system that it is more clean. (cleaning up the smallest amount of code possible)
5. after cleaning up your code your problem either is already solved (happens often in my experience) or gets some fixing now (done by you of course).
With this process you reach many goals at once and make sure to not put in resources that are not nessesarily needed. Also you can see that this process is able to handle ugly code, situations where unit tests where forgotton to write and basically many kinds of mistakes that coders do because they are humans (error prone and lazy).
By the way, the same process also works for new feature requests.
Yes, there's particular style of code called "self-documenting." It's a good style and I recommend that everyone learn it. However, it doesn't do everything. It's good at explaining what happens and how it happens but not why. Comments are for explaining why. Without knowing the original programmer's intention, I'm still mystified.
Awesome. I'd add "why not" as well, that is: why you discarded some alternative solution? That's very important especially when refactoring is involved. Some programmer could come by and think: "Why she didn't just do like this? It would have been much easier."
I find that explanations about discarded solutions is (almost) always missing from both comments and higher-level documents.
I grant that all code can't be self documenting. But you don't commit suicide just because you're going to die at some point anyway. Instead, you try to make your life as long and happy as possible.
Your highest priority should be to make your code self-documenting as possible, even though that isn't always possible.
That said, the author does have a valid point in that public APIs do need documentation. But I wouldn't go so far as to say that every method (private or not) needs documenting. Unnecessary comments and documentation should be treated like any other kind of useless code. They should be removed.
Perhaps not, but I don't think inline documentation is often very useful either and breaking code density is a jarring thing. External documentation exists for a reason (even if it's just doxygen-izing your inline docs instead of pointing people at the direct source), and I much prefer reading (and writing) short READMEs, examples, or tutorials than digging through implementation code if I'm interested in using something. And if I'm integrating anything non-trivial I don't think little comments saying "/* * executes the passed query string, not using prepared statements, throws SQLException, returns nothing */ public static void executeSql(String query) throws SQLException {" are useful or worth my time. Write comments when something needs some explanation not clear from the context, save the academic comment-everything documentation for enterprise busywork or academia.
I think you're mixing up inline documentation with api documentation.
For inline stuff where it's explaining a complex/dense lump of code, it's useful to keep it as close to the original code as possible, so that if somebody updates the code, they're more likely to see/update the comments as well.
I think people are too harsh with the author. He is clearly in the beginning of his hacker path. I think everybody who disagrees here can remember a time, when he thought the same way. The author here got a basic idea very correct: You want your code to be readable. And he still has to learn, that good code itself can be (and often is) the most readable way to express a problem and its solution. Often there just is no better way to express, what the coder wants to say.
For everything we code we have to keep in mind that every line we write must have a meaning. That is true for code as much as for documentation. If the problem is complex and the code is hard to grasp, but it is well written, then probably every line of documentation you write will degrade the readability and also end up beeing a waste of the time for its author and its reader.
I don't think people are being too harsh. He put his opinions out there in a very proscriptive way. He didn't invite discussion, he merely dictated his opinions. And he is quite wrong.
Additionally, his blog is called ProgFu. That gives the impression that he is highly skilled and experienced; an authority to be heeded, like the sensei of a dojo. But if you look at his writings in total you can see that he's pretty green. His factual pieces are really useful, the opinion pieces less so.
While I'm thinking about it: I'm dismayed by this trend of bloggers dispensing programming advice like they are Miyamoto Musashi himself (although he would never display such hubris). Exchange of information is what's important. If you have a personal experience, share it, and perhaps discuss the lessons you've learned. But, please, don't write articles merely stating your opinions without backing them up with some evidence or experience.
"Almost all programmers type fast, say 400+ characters
per minute. So how long does it take to write one two
lines of simple text explaining your code? 15 seconds
maybe?"
OMG - is this true? He can't be talking about code - can he? I'm lone programmer & self taught. If it's true I must really suck because it takes me so much longer it's not funny. LoL - I have to stop and think, for minutes, almost all the time.
I don't usually have to stop and think for documentation, though. That's the idea - you're just putting down what's already in your head so that the maintainer can read it.
That said, I usually find that the documentation I write ends up becoming out-of-date about 5 minutes after I write it, because code changes in the process of writing it down. I might write down a docstring to clarify my thoughts, but then the function I actually write doesn't do exactly what I thought it would, and I have to go back and remove or cleanup the docstring later.
I like Google's viewpoint on this... "incorrect documentation is a bug, and should be fixed." Complaining about the code diverging from the comments therefore comments are worthless is silly imo.
While documentation should not be over the top and code should be readable, I am sick of seeing completely uncommented functions that are non-obvious. There is a happy medium of having easy to read and well styled code and accompanying documentation that explains any gotchas and difficult sections. Sometimes just a written out purpose for the function can be surprisingly useful.
If you've worked in a company with a large shared codebase, you learn to love good comments.
I don't think every function needs a comment, necessarily, but I have seen "self-documenting" used as an excuse for not documenting anything at all. It's easy to declare code understandable and readable when you're the one who wrote it.
Agreed. While the author tends to take the viewpoint that attempting to write self documenting code is almost a bad thing, and that's very wrong, I understand his frustration, because too many programmers these days seem to think that documentation in the comments are either superfluous or a sign of bad code, and that's also just flat wrong. It's a shame that the author takes the opposite extreme.
Like most things in life, code documentation requires balance, and one should strive to create code that is easy to read and understand, but good code cannot be easy to read and understand in all circumstances, and comments should be used in any situation that confusion could possibly arise.
For my own code, aside from commenting on obviously confusing sections, I tend to create functions that have an easily understood purpose when called, but I tend to use 1-2 lines of comments when I declare the function so that I can feel reasonably sure that anyone reading my code wont have too many questions. I've found through feedback that this is a fairly functional method of documentation.
I've also seen that used as an excuse, along with almost everything else you can think of. We've all seen the results of "I'm adhering to each and every rule but coding how I want anyway" coders.
That is a very good point. But it is not contradicting the main point of most people here. Of course there is good documentation and important documentation. It is just that most of the times your code does not need a big bloat of text around it.
And I would say that your point is a much better example than the one used in the blog post.
I'm not going to argue that you should not document your code, but two things come to mind:
1) With the backup example- you have indeed moved complexity elsewhere, but the idea of that kind of setup is you logically separate complexity into a hierarchy so that the proper segment can be rapidly located, and is easy to comprehend because it is isolated, and small chunks of complexity are not all that hard to understand.
2) Every example of well written self-documenting code I've ever seen is pretty much superior to the alternative in every way, with the possible exception of small performance hits. It's generally a good goal to shoot for, whether you document your code or not.
I also disagree with it. Good code is as self-documenting as possible. Any gotchas should be explained in comments, but correct naming is way more valuable than comments explaining what a function does.
Any code that fails to be self-documenting needs to be refactored immediately.