June 8, 2018 at 6:58 am
Oooh, my favorite pet peeve!
Comments are your friend. Now, that isn't to say you shouldn't spend every effort making the code readable, refactoring long routines into short, well-named functions and short subs, but you WILL NOT REMEMBER what they do a month from now. You WILL NOT BE ABLE to follow code you (or worse, someone else) wrote six months from now without starting from scratch unless you have extensive, well-written, comments.
Our company standard says 70% of the lines in a program should be comments. I'm a big fan of largely linear "outline" programs, and that includes comments. Comment the why and the how, but don't forget the "what" (i.e. the purpose of a function).
Another BIG point in comments, you should always write 2 programs, one in code and one in English and make sure they stay synchronized. You change the code you damn well change the comments too. Comments should always include headers for sections, and other "pretty" elements that visually divide code into discrete sections.
Write comments as though you were teaching a newbie how the program works. Because in six months that newbie will be you.
Yes, the upfront effort is enormous. It's hard, it's tedious and it roughly doubles the coding time. But that investment pays back huge dividends every time you have to review and modify the program. Which, in business environments, is constantly.
No one is able to read code with the same speed and clarity they read English. NO ONE. Yes, naming conventions and programming style rules help tremendously, but they aren't nearly enough.
I've worked for bosses that complained I was commenting too much. Those complaints continued until they had to fix my code. After that...they got quieter. 😀
Comment correctly (i.e. generously and in the mindset of a teacher) and you won't regret it. You'll save time down the road. Failing to comment properly is just another example of technical debt. Or maybe eating your seed corn...
June 8, 2018 at 7:38 am
My standard for the past decade has been to maintain a comment section within the header of each stored procedure and view. For each commit that contains a functional modification or bug fix, I will add a new line that consists of: date/time, TFS or JIRA tracking number, my name, and a one sentence summary of the purpose of the modification. I like seeing the contiguous history of modifications made to a procedure in one block. I find it useful to reference the name of the stake holder who requested the change, but I don't go into detail about why the change was made, because the entire back story and requirements can be referenced using the tracking #. Also, I don't comment each individual line of source code modified, because that leads to clutter over time and can be better done via the version compare feature of the VCS.
For example:
2018/05/02 DBA-3022 Eric Russell - This procedure was created to serve as source for the Renewal Retention report.
2018/06/08 DBA-3127 Eric Russell - Per request from John Doe, exclude from report those accounts with no payment activity for past 180 days.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
June 8, 2018 at 7:43 am
Personally I've never had comments be of any use when fixing a system, they're either out of date, wrong, a combination of both, or in rare cases they're actually accurate but it's irrelevant because you can't trust them when the failure rate is so high.
A vcs commit history and clean coding patterns provide much more help and information about how and why it looks the way it does.
June 8, 2018 at 8:09 am
David.Poole - Friday, June 8, 2018 1:21 AMI've just finished reading "Clean Code" by Robert C Martin. It takes a dim view of commenting code preferring instead to refactor the code to the point where all functions and methods are simple and have meaningful names. The view is that if the name of your function cannot express what the function does then the function is probably too complex and needs refactoring.
I tend to agree, though this can be a rabbit hole of cleaning code and not getting new work done.
What I wish is that we spent 20% of time fixing/improving/refactoring old code.
June 8, 2018 at 8:11 am
xsevensinzx - Friday, June 8, 2018 5:31 AMI follow the Pep 8.0 standard when doing comments in Python. I follow the same standard for the most part in SQL.I also mix this with the Google Python Style Guide to even further enhance my code and comments.
So, does this help in the long run when it comes to code comments? Sure. When you start getting into complex projects, I've often have forgotten what things do. Take the below code example with a simplistic algorithm that's written in such a way that humans can easily get confused.
def array_query(s, t, i, j):
What I hate is single letter variables except for counters. Everything else should be more descriptive
June 8, 2018 at 8:13 am
roger.plowman - Friday, June 8, 2018 6:58 AMComment correctly (i.e. generously and in the mindset of a teacher) and you won't regret it. You'll save time down the road. Failing to comment properly is just another example of technical debt. Or maybe eating your seed corn...
I always think, what would I want to know if I come upon this in 6 months when I'm thinking about some other app x and I'm stressed by something at home. Meaning, my head isn't here. How do I get this quickly to get out of the office as soon as I can.
June 8, 2018 at 8:35 am
Great topic!
I've been all over the map, as to how I comment code. I hate it when I came across some code that hasn't any comments, especially badly written code, so when I started coding I was very verbose. I'd write things like:
//concatenate the first name to the last name
string fullName = firstName + " " + lastName;
Then I read where that was bad, to comment exactly what I had done in the code. I realized that I was being painfully obvious, so I stopped. Then I swung too far the other way and almost didn't comment any code.
Today, I tend to comment why I did something. Especially if I had tried something else and found that it didn't work. I want to make it so that if I or someone else comes back to that code 6 months later, I/they will know why I did what I did and why I thought doing it the other way didn't work.
But I've come to the conclusion that my approach to commenting code is continually evolving.
Kindest Regards, Rod Connect with me on LinkedIn.
June 8, 2018 at 8:44 am
Steve Jones - SSC Editor - Friday, June 8, 2018 8:13 AMroger.plowman - Friday, June 8, 2018 6:58 AMComment correctly (i.e. generously and in the mindset of a teacher) and you won't regret it. You'll save time down the road. Failing to comment properly is just another example of technical debt. Or maybe eating your seed corn...I always think, what would I want to know if I come upon this in 6 months when I'm thinking about some other app x and I'm stressed by something at home. Meaning, my head isn't here. How do I get this quickly to get out of the office as soon as I can.
I think that is a good approach.
I was bit once when another developer added a feature to a system and to test the code, commented out a block of code that does a redirect from http:// to https://; the commented out code was checked back into Subversion. When another programmer and I started developing the system, we had a configuration setting called DEVELOPMENT_MACHINES so we wouldn't do a redirect if we were debugging from our desktops. I added the following code above the check if it was https or not.
// Ralph Hightower: DO NOT COMMENT THIS CODE OUT FOR TESTING!!! It may go into production like that!
// Instead, add your local machine name to this settings parameter: DEVELOPMENT_MACHINES
June 8, 2018 at 9:43 am
I would never rely solely on an external issue tracking and source version control system to comment changes to source code. The reason I say this is because at a company I worked for in the past, the TFS server (administrated at that time by the QA / Production Control team, not the DBA team) crashed, and there were no backups. I feel we all need to maintain some level of functional documentation and basic change history annotated in every source code file that we modify. :unsure:
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
June 8, 2018 at 10:07 am
Eric M Russell - Friday, June 8, 2018 9:43 AMI would never rely solely on an external issue tracking and source version control system to comment changes to source code. The reason I say this is because at a company I worked for in the past, the TFS server (administrated at that time by the QA / Production Control team, not the DBA team) crashed, and there were no backups. I feel we all need to maintain some level of functional documentation and basic change history annotated in every source code file that we modify. :unsure:
ouch
-------------------------------------------------------------------------------------------------------------------------------------
Please follow Best Practices For Posting On Forums to receive quicker and higher quality responses
June 8, 2018 at 11:07 am
I find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.
Most code should also be self documenting so it will require minimal comments.
June 8, 2018 at 11:13 am
jonathan.crawford - Friday, June 8, 2018 10:07 AMEric M Russell - Friday, June 8, 2018 9:43 AMI would never rely solely on an external issue tracking and source version control system to comment changes to source code. The reason I say this is because at a company I worked for in the past, the TFS server (administrated at that time by the QA / Production Control team, not the DBA team) crashed, and there were no backups. I feel we all need to maintain some level of functional documentation and basic change history annotated in every source code file that we modify. :unsure:ouch
Yeah, it happens when no one truly owns the database.
It can also happen with cloud hosted databases too.
https://techcrunch.com/2017/02/01/gitlab-suffers-major-backup-failure-after-data-deletion-incident/
Not wanting to go off topic but..
#1 All the database servers should be managed or at least owned by the DBA team.
#2 All production or mission critical databases across the enterprise should get backed up; not just the line of business databases, but also databases supporting internal applications.
#3 Don't entirely rely on cloud application or database providers to perform all your backups. Make sure you backup / migrate / file copy or whatever your database from the cloud to another secure location on a regular basis.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
June 8, 2018 at 11:34 am
I lean more to the 'Why' types of comments and what it is I'm trying to achieve. I'm still waiting to work with elegantly managed code where everything is laid out in an intuitively obvious manner. My software world is inhabited by Frankensteins and spaghetti. Knowing the goal or even why a particular code decision was made helps me prevent second-guessing the developer and possibly repeating their mistakes. It also helps explain deviations from the original design so I can factor them into my own decisions.
An aside... years ago I watched a video where John Carmack was talking about why he had released some source code to the public domain and one of things he mentioned struck a chord with me and he basically said the code itself wasn't worth nearly as much as the countless decisions that when into making it.
June 8, 2018 at 11:43 am
Brain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
June 8, 2018 at 11:59 am
roger.plowman - Friday, June 8, 2018 11:43 AMBrain2000 - Friday, June 8, 2018 11:07 AMI find comments are easier to return to months or years later if you leave out almost all articles, such as "it" or "this". There's nothing like looking back and trying to figure out what "apply this thing to that so it works out right" even means.Most code should also be self documenting so it will require minimal comments.
Except there is no such thing as self-documenting code. The problem is code needs to be concise to the point it loses context. You keep that context in your mind while you're writing it but context rarely makes it to long term memory. Thus 6 months later you have the code but no context.
Comments record the context so you don't lose it.
Viewing 15 posts - 16 through 30 (of 41 total)
You must be logged in to reply to this topic. Login to reply