Re:Please do not attempt to simplify this code
by dwild on Friday December 28, 2018 @11:07AM
(#18777524)
Personally I consider that if the code don't speak for itself, then it's most probably bad code, if it's not, add a comments explaining why it's not.
> spilling a few sentences as a minimal kind of pseudocode before writing what you want
Isn't it simply repeating the code you'll write? Which in the end, will be just as bad as the code alone or will lose time of the one that will read it afterward.
Sure it's hard to write good code, sure it's not always obvious what's bad code, but that's a big reason why the review process is there. It's not only to catch mistakes, it's also to see if someone else can understands what the code meant, the context, the decisions, etc... Sadly many just go quickly over it and just check for obvious mistakes.
Code without specification is a maintenance nightmare, a pure liability, a ticking time bomb.
And sure, unless you're creating the control system of a nuclear reactor/warhead you don't have to go full Coq and CMMI5 and "high assurance" and whatnot, but spilling a few sentences as a minimal kind of pseudocode before writing what you want (a function, a class, a method, change the build system, refactor a big ball of if-s) is almost ideal. It helps you double check yourself, and it helps reviewers too. (Throwing there links to some issue tracker is also nice, but just the links are not very helpful.)
If you have to write docs later, it's hacking (reverse engineering), not engineering.