Your Code is Not Self Documenting
progfu.com
progfu.com
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.
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.
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.
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.
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.
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.
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.
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.
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?"
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.
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.
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.
And I would say that your point is a much better example than the one used in the blog post.
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.
// test 1 + 1 == 2
function testOnePlusOneEqualsTwo(){
return (1 + 1) == 2;
}