May 21, 2020 at 12:00 am
Comments posted to this topic are about the item Writing Before Reading
May 21, 2020 at 6:50 am
One of the reasons I like Python is that one of its design goals is readability.
I've always found SQL to be highly readable too.
I really took Bob Martin's Clean Code book. https://www.amazon.co.uk/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882
Following his approach can help you make your code easily read.
I've mentioned before that although you write code to perform a desired action you can write it to be used as a teaching aid.
May 21, 2020 at 8:49 am
Wow! - I have learnt that there are names for some obvious tendencies and people have been researching some of them for decades. I have been further educated. (Now, I am just thinking of some of my friends' taste in music!)
As a contractor, I often have to deal with other people's code (recently, 12,500 lines in one routine.) So I have got familiar with the unfamiliar. Sometimes I do reformat it (like in the case where the developer had put all the code in one line - no CRs anywhere) to help me understand the logic. Just the task helps as well as the result.
I do look to learn - whether the previous developer has a usage or technique I would do well to use. So I hope I improve all the time but the familiar, that is what we find easiest to remember and in which we feel most secure.
May 21, 2020 at 11:10 am
...
Sometimes I do reformat it (like in the case where the developer had put all the code in one line - no CRs anywhere) to help me understand the logic. Just the task helps as well as the result.
I do look to learn - whether the previous developer has a usage or technique I would do well to use. ...
Yes, I've reformatted the code of others before attempting to debug or modify it. Never encountered all the code in one line, but there's been quite a few cases of extremely long lines that I had to break up just so I didn't have to continuously scroll back and forth.
Sometimes it's really a head-scratcher: "What the heck was he trying to do here?" And sometimes after I figured it out, like you, I found a technique to use. Other times I found a technique to avoid at all costs!
May 21, 2020 at 12:44 pm
There's a secret to reading code. 🙂
Don't try.
Or rather, do it only once. Code is called code for a reason. Even the best written code is not written for readability by humans. It's written to be efficient for the computer. So despite all the code-writing best practices (linear flow wherever possible, preflight check patterning, good variable names, constants instead of magic numbers, etc. ad nauseum) code is still at best a (very) foreign language, one you will never be fluent in because there are as many "dialects" as there are developers.
Which is why at our company we specify that wherever possible code requires 70% comments to 30% code. Of course those comments should be "why" not "how" comments, and it does take effort to maintain them and make sure code changes always have comment updates as well, but the end result is rapid comprehension because you read English, not code.
Our company policy is to read the comments first, then quickly see if the code makes sense and matches the comments. If the code writer followed commenting best-practice it will. And having annotated code means having understandable code--without the need for analyzing the code. Much faster!
Of course most developers HATE comments with a passion. They hold that well-written code doesn't need them, that well written code is self-documenting. Comments make the code too long and verbose, you can't see the code for the blasted comments. And 70% comments to 30% code???? Are you joking?
Visual Studio supports code folding and code hiding. There's this nifty little extension called Remarker that lets you change comment size and color based on the type of comment. Comment headers can be normal size while comment bodies can be in a smaller font. You can then hide the comments by folding them away giving you the best of both worlds.
SSMS is a little less flexible but since SQL is so antiquated anyway it pays to keep stored procedures simple. Even so anything of any complexity should still follow the 70% comment rule. Unless it's just a simple SELECT of course. But even then you should explain WHY the stored procedure exists.
Follow comment discipline religiously and you'll find that at least in-house code doesn't have to be read--without a cheat sheet, at least! Even your own code will mystify you six-months later. Oh, and "well written code is self-documenting"? It's a LIE.
c1
May 21, 2020 at 1:45 pm
+1 Billion to Roger Plowman for his post above. I'll also add that commenting code when you're writing it is pretty simple. The first thing I normally do is to write the comments of the things I need to get done and why. That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.
Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.
I'll also state that doing comments this way really helps write code faster especially if you're frequently interrupted. You don't have to ask yourself "Now where was I at and what the hell was I thinking" because it's in the comments.
My rule for comments is "If you remove all of the code, the comments that remain should provide you with enough information to draw a functional flowchart".
Unfortunately, it's becoming a lost art and companies pay dearly for it.
--Jeff Moden
Change is inevitable... Change for the better is not.
May 21, 2020 at 2:57 pm
Jeff Moden wrote:...The first thing I normally do is to write the comments of the things I need to get done and why. That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments...
Stealing this.
They say the highest compliment that can be paid is imitation. Thank you for the compliment. 😀
--Jeff Moden
Change is inevitable... Change for the better is not.
May 21, 2020 at 3:14 pm
+1 Billion to Roger Plowman for his post above. I'll also add that commenting code when you're writing it is pretty simple. The first thing I normally do is to write the comments of the things I need to get done and why. That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.
Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.
A lot of what you're specifying here is the idea of TDD. With the plan, having the results specified helps to ensure you're covering the requirements that you want to meet.
May 21, 2020 at 3:37 pm
Great article, Steve! I've held to both NIH stance at times and the proudly found elsewhere stance at other times. I'm not sure which is right. Perhaps the extreme of both is wrong and somewhere in the middle is the best way to go.
Kindest Regards, Rod Connect with me on LinkedIn.
May 21, 2020 at 4:47 pm
Jeff Moden wrote:+1 Billion to Roger Plowman for his post above. I'll also add that commenting code when you're writing it is pretty simple. The first thing I normally do is to write the comments of the things I need to get done and why. That also creates a bit of a "functional plan" of what I need to do and then I fill in the code between the comments.
Of course, you sometimes need to adjust the plan and the first thing you should do is adjust the comments and then fill in the code.
A lot of what you're specifying here is the idea of TDD. With the plan, having the results specified helps to ensure you're covering the requirements that you want to meet.
Thanks for the feedback, Steve. Heh... it's amazing what they end up calling things. I've been doing this type of thing since I worked on old unit record equipment and punched cards starting way back in (IIRC) 1969. The concept of "comments in code" obviously couldn't be applied but I always built a functional flowchart and a wiring diagram for the "program board" first.
--Jeff Moden
Change is inevitable... Change for the better is not.
Viewing 11 posts - 1 through 10 (of 10 total)
You must be logged in to reply to this topic. Login to reply