Legacy Code Documentation
-
(nervous laugh) Hahahahaha deep breath Hahahahaha!!! When I'm going through undocumented legacy code, I write code comments worthy of a 1st year college student. If there are function comments, I'll check them, add missing parameters comments and stuff like that. We lost many, many years of expertise (retirements) in a short amount of time; so there is a lot of documentation going on.
CI/CD = Continuous Impediment/Continuous Despair
similar boat to you with retirements and a vast change in staff
-
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
These are strange times, we got some young developers who were told by their teacher at the local school that documentation was not necessary, said teacher seems to be a follower of the "code should be self documenting" doctrine. :~
-
These are strange times, we got some young developers who were told by their teacher at the local school that documentation was not necessary, said teacher seems to be a follower of the "code should be self documenting" doctrine. :~
Maybe have them analyze a complicated method from your code base, after the comments are removed.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment "Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst "I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
-
Maybe have them analyze a complicated method from your code base, after the comments are removed.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment "Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst "I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
Well, to be fair, some of our code is so complicated that even with documentation no one can understand it anymore :-\
-
Well, to be fair, some of our code is so complicated that even with documentation no one can understand it anymore :-\
Maybe one of the rookies is a savant and could explain it to you, then you could document it better? :laugh:
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment "Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst "I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
-
These are strange times, we got some young developers who were told by their teacher at the local school that documentation was not necessary, said teacher seems to be a follower of the "code should be self documenting" doctrine. :~
Younger programmers, yes I know them and have experience with them. Yes, they can program very nice websites for you. They also know all the new features of e.g. c#. But it seems that they have no ability to get to grips with a specific business, let alone understand its basics in the very minimal basics. :sigh: [Edit] Would you trust a surgeon who simply knows how to cut open a body part, do something on what's inside it and sew it back up... ... or would you not prefer more, it if the surgeon also had specific knowledge of how to operate on a heart, a hip joint or a knee, etc.?
-
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
MarcusCole6833 wrote:
Is the code documenting itself good enough?
I am personally a big fan of using descriptive variables such that the code becomes self-explanatory. I also have a standard set of names for common-use objects that could incriminate identify me as the author. Edit: That said, when the intent is not clear, or you/they are doing something 'clever', then documenting/commenting is encouraged. Comments may or may not get updated, but the code doesn't lie. :laugh:
"Go forth into the source" - Neal Morse "Hope is contagious"
-
MarcusCole6833 wrote:
Is the code documenting itself good enough?
I am personally a big fan of using descriptive variables such that the code becomes self-explanatory. I also have a standard set of names for common-use objects that could incriminate identify me as the author. Edit: That said, when the intent is not clear, or you/they are doing something 'clever', then documenting/commenting is encouraged. Comments may or may not get updated, but the code doesn't lie. :laugh:
"Go forth into the source" - Neal Morse "Hope is contagious"
I think calling it "self-explanatory" is a bit of a stretch. Although consistent naming is a big plus and something I strive for, it's also important to document why it was done the way it was unless it's obvious. Along the lines of your final point, I've referred to code as the urtext.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
"Is the code documenting itself good enough?" You're joking, right? I am the sole proprietor of a legacy system written in the 80s. Technically, I've retired, but I've given this one customer the option of lifting the production (note: production) system to today. It's a re-write (the core functions) but most of the code goes away due to a functional database, report writer and C++ or .net. The group involved is part of a huge international corporation, so crickets.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
Most developer document the wrong things. Far too often, they repeat what the code line says, whether like "Here we set i to the value 5" or repeat the parameters of the method heading, "explaining" e.g. "numberOfApples: The number of apples". Or, when asked for more high level, code independent documentation, they present a block chart with Application, Database and Network modules. What other developers need lies in between: A documentation of the purpose of each code module, of its interaction with other modules. Replace 'module' with 'class' as appropriate. The data structures - how they are interlocked, what they represent as a whole - that usually means, across several object classes. To draw a line: I want off line - in the sense: off the code lines - documentation to go down to the deepest level where it is still independent of the programming language. You should be able to build those modules, those data structures, in Python, in C++, even in Visual Basic. You document the interfaces between modules, not only the syntax (name, parameters) but the dynamics as well. That will help the next code maintainer on the right track! And, these interactions are far more stable than the individual code lines; you can make a lot of changes without invalidating the documentation. Every now and then it may need to be extended with new interactions or parameter options, yet all the old stuff remains valid. When you get down to code, you may of course add code comments - but without repeating the off code line documentation; there is no need to. Obviously, you should avoid 'Here we set i to 5' style comments, and you should use descriptive type and variable names. When you delete code lines, you delete the accompanying comments. When you change code lines, you change the accompanying comments. End-of-line comments (lined up at col. 70 or 80 not to blur the code) is a lot better for keeping them up to date than pushing them to the top of the method. But these code comments are far less essential. You read them after you have studied all the off line documentation, and know the interactions, the data structures, the interfaces. What is left is to understand how these interfaces are realized, within a single module/class. That is usually a far simpler task than grokking the structure of the entire program system as a whole. I do like to have (i.e. both make and read) code comments, but if I could have a choice between code comments and a system documentation from immediately
-
"Is the code documenting itself good enough?" You're joking, right? I am the sole proprietor of a legacy system written in the 80s. Technically, I've retired, but I've given this one customer the option of lifting the production (note: production) system to today. It's a re-write (the core functions) but most of the code goes away due to a functional database, report writer and C++ or .net. The group involved is part of a huge international corporation, so crickets.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
MarcusCole6833 wrote:
Is the code documenting itself good enough?
I am personally a big fan of using descriptive variables such that the code becomes self-explanatory. I also have a standard set of names for common-use objects that could incriminate identify me as the author. Edit: That said, when the intent is not clear, or you/they are doing something 'clever', then documenting/commenting is encouraged. Comments may or may not get updated, but the code doesn't lie. :laugh:
"Go forth into the source" - Neal Morse "Hope is contagious"
kmoorevs wrote:
you/they are doing something 'clever', then documenting/commenting is encouraged.
I maintain as a strong rule: 'Clever' code should be avoided, if at all possible. If it can be rewritten in a more readable way, do so -- even if timing of that specific loop shows that it takes 40% more time. Most likely is is 0.01% of the total run time for the application.
Comments may or may not get updated, but the code doesn't lie. :laugh:
Well ... The comment may still be the honest truth of what the code was intended to do. The code may be honest about the coder's misconceptions, or possibly his intent to impress with his 'smartness', without succeeding :-)
Religious freedom is the freedom to say that two plus two make five.
-
MarcusCole6833 wrote:
Is the code documenting itself good enough?
I am personally a big fan of using descriptive variables such that the code becomes self-explanatory. I also have a standard set of names for common-use objects that could incriminate identify me as the author. Edit: That said, when the intent is not clear, or you/they are doing something 'clever', then documenting/commenting is encouraged. Comments may or may not get updated, but the code doesn't lie. :laugh:
"Go forth into the source" - Neal Morse "Hope is contagious"
kmoorevs wrote:
Comments may or may not get updated, but the code doesn't lie. :laugh:
Unless that code is being refactored and the naming butchered by some other dev. While I do agree good naming is important, it doesn't remove the need for comments completely. Blanket statements is typically the tell tale sign of the inexperienced.
Jeremy Falcon
-
Most developer document the wrong things. Far too often, they repeat what the code line says, whether like "Here we set i to the value 5" or repeat the parameters of the method heading, "explaining" e.g. "numberOfApples: The number of apples". Or, when asked for more high level, code independent documentation, they present a block chart with Application, Database and Network modules. What other developers need lies in between: A documentation of the purpose of each code module, of its interaction with other modules. Replace 'module' with 'class' as appropriate. The data structures - how they are interlocked, what they represent as a whole - that usually means, across several object classes. To draw a line: I want off line - in the sense: off the code lines - documentation to go down to the deepest level where it is still independent of the programming language. You should be able to build those modules, those data structures, in Python, in C++, even in Visual Basic. You document the interfaces between modules, not only the syntax (name, parameters) but the dynamics as well. That will help the next code maintainer on the right track! And, these interactions are far more stable than the individual code lines; you can make a lot of changes without invalidating the documentation. Every now and then it may need to be extended with new interactions or parameter options, yet all the old stuff remains valid. When you get down to code, you may of course add code comments - but without repeating the off code line documentation; there is no need to. Obviously, you should avoid 'Here we set i to 5' style comments, and you should use descriptive type and variable names. When you delete code lines, you delete the accompanying comments. When you change code lines, you change the accompanying comments. End-of-line comments (lined up at col. 70 or 80 not to blur the code) is a lot better for keeping them up to date than pushing them to the top of the method. But these code comments are far less essential. You read them after you have studied all the off line documentation, and know the interactions, the data structures, the interfaces. What is left is to understand how these interfaces are realized, within a single module/class. That is usually a far simpler task than grokking the structure of the entire program system as a whole. I do like to have (i.e. both make and read) code comments, but if I could have a choice between code comments and a system documentation from immediately
that's pretty religious ;) Seems to me a bit of a pet peeve of yours. Mine as well. I'll swing this in a different direction. There are a few people I've worked with that I term "whiz kids." Their minds work so fast, 5x faster than mine, that everything is intuitively obvious. Not one damn line of comments. No doc to save anyone's lives, nothing. I simply gave up. I completely concur about not documenting loops and i++, but module level comments are necessary. And ffs, tie the code comments back to external documentation. Now, 40 years later, no one gives an elephant. I've worked at (counting....) 9 companies and myself, and there is only one person I can count on to write proper documentation. It's simply pathetic.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
that's pretty religious ;) Seems to me a bit of a pet peeve of yours. Mine as well. I'll swing this in a different direction. There are a few people I've worked with that I term "whiz kids." Their minds work so fast, 5x faster than mine, that everything is intuitively obvious. Not one damn line of comments. No doc to save anyone's lives, nothing. I simply gave up. I completely concur about not documenting loops and i++, but module level comments are necessary. And ffs, tie the code comments back to external documentation. Now, 40 years later, no one gives an elephant. I've worked at (counting....) 9 companies and myself, and there is only one person I can count on to write proper documentation. It's simply pathetic.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
Contrary to my last(vastly misunderstood post), this is not apparent, it simply is (for real). I am an OF and have noticed how "newer generations" choose NOT to use (simple) old, proven methods , stuff. My manager did not use AI or RTFM - his "comment or else " was based on "what will happen if you get run over by a bus and your code is not documented / commented?" For those hard of hearing - undocumented / uncommented code was against company interest, period. I am not a wiz kid, but if the code task is to test HARDWARE , CLOSE TO REAL TIME, and if the code is not documented , commented AND is missing ANY time reference - it will not "just " APPARENTLY fail - it will fail for sure. IMHO self documented code is oxymoron
-
Never trust documentation. There is no guarantee the last developer updated it when they changed the code. You can read it as a guide. So trust, but verify.
Hogan
-
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
All documentation is out of date as soon as it's written. Code is never out of date.
-
Never trust documentation. There is no guarantee the last developer updated it when they changed the code. You can read it as a guide. So trust, but verify.
Hogan
I hate that, and it's why I lean toward not commenting, and expressing intent through code, wherever I can. Comments are a curse, even if they're sometimes necessary.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Questions Is it Maintained? Do you look for it or just explore the code? What do you do if it is not there? Is the code documenting itself good enough?
Is it really just the code, or a whole system? If a whole system, check and/or create a high-level overview, even if it "should be obvious" and make sure you have the documentation necessary to make a change, rebuild, test, distribute and install. (I.e. you have to go through that process to be sure it works). As for code, depends partly on how much expertise in the coding language(s) you think will be available if a change is necessary, particularly if people have used unusual language features or coded in an unusual way compared to "normal industry practice" - perhaps make a few general remarks noting such stuff.
-
Contrary to my last(vastly misunderstood post), this is not apparent, it simply is (for real). I am an OF and have noticed how "newer generations" choose NOT to use (simple) old, proven methods , stuff. My manager did not use AI or RTFM - his "comment or else " was based on "what will happen if you get run over by a bus and your code is not documented / commented?" For those hard of hearing - undocumented / uncommented code was against company interest, period. I am not a wiz kid, but if the code task is to test HARDWARE , CLOSE TO REAL TIME, and if the code is not documented , commented AND is missing ANY time reference - it will not "just " APPARENTLY fail - it will fail for sure. IMHO self documented code is oxymoron
What is an OF, and more to the point, what other post? Inquiring minds want to know (I looked at the thread, and this is your first post). But, I completely agree with your comment.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
