|
Comments are necessary for one simple reason, "I don't know what you are thinking when you wrote or changed this code". Documentation is removed from the code does not live with the code and can and will be lost. I don't know how many times I have heard, "We don't know what happened to the docs".
Still don't think comments are needed? Ok then try this exercise. Write some code to solve a problem you have today. Ok now put the code away and don't look at it for 6 weeks. In 6 weeks go back to the code and make a change, fix a bug do something to it. Time how long it takes you to 'remember' how the code works and what you need to do to make the fix.
Still not convinced? Perform the same process, but this time put comment headers in explaining what you were thinking when you wrote the code. Put the code away for 6 weeks and then perform the same test again only this time with the comments.
Don't have time for all this process? What to jump to the result? In the first case, it will take you a fair amount of time reading and trying to remember what you were trying to do and how something worked. In the second case, you will find that you can make the update and or fix it in less than a few minutes.
Now put yourself in someone else's shoes. If you went through this with your code and you wrote that code imagine how the next developer to pick up your code will feel? Ever wonder why the next devs end up throwing out, refactoring, or reworking lots of code? Guess what it's not as self-documenting as you want to think.
I learned this lesson back in the assembler days. I wrote a one-off tool to solve the problem I had at the time. A week later (yes only 1 week) I needed the code again to solve the same problem, but it did not work on this 'slightly' different set of data. No problem I thought, I'll just fix the bug. Two hours later I was finally starting to understand how the tool was supposed to work and where the problems were. That was the last time I ever wrote code that did not have comments.
|
|
|
|
|
If I'm heads-down in a project during a coding frenzy, I forget after just a few minutes a lot of times. 
Of course, I'm old, and I have to consciously put brain time toward trying to get to the bathroom in time, so unimportant stuff like what a method that I just wrote does takes a back seat to the more immediate need...
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
Of course, there is the other school of thought I don't subscribe to personally. If the code was hard to write it should be extremely difficult to modify, and impossible change". From time to time get to work with SDEs that think this is the way code should be.
|
|
|
|
|
Quote from - Real men don't use Pascal
It was difficult to write it should be difficult to understand.
But that was meant to be funny.
"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP
|
|
|
|
|
But if it was written and commented well, it will be relatively easy to understand.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
I actually got in trouble with my boss once for that...Quote, "Your code is too easy to understand. This is not good as management won't need you later to fix it". I left that job about 6 months later and got a better one. 
|
|
|
|
|
Totally agree - ask anyone that's ever written any assembler code
"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP
|
|
|
|
|
I once had a boss that was hemming and hawing about a decision. Finally, after I got tired of waiting, I asked, "well, why not?" Since no good reason could be found I was given the OK. Maybe you should take that approach - "Why not?"
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
The main problem is that nobody wants to take on the task of implementing it in the apps they're responsible for. We have four devs on one (web) app, and the remaining six devs split their time among the other 11 apps. I am the lead on the team of four. My team is ready to jump on it, the other guys, not so much, because it means they'd have to actually do some work. The prospect of testing is what turns them off the most, I think, because implementation seems dead easy.
In short, despite the need, nobody wants to put in the time.
I think another problem is that they feel like I'm making them look bad by taking initiative where they wouldn't.
I had a friend way back in the 70's that was in the Marines, who liked to say, "In the absence of other orders, attack."
That's how I do it.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
Yes, I can see that being a problem. I am the same way - I seem to be much more proactive than others. I think it's mostly because I prefer to address issues before they become problems because there seems to always be enough problems to deal with.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
"I didn't mention the bats - he'd see them soon enough" - Hunter S Thompson - RIP
|
|
|
|
|
I too have an aversion to having to "tweak" anything when moving between environments. I use a method that involves only one line of code, inserting the IIS instance ID into the connection string name. Then I code all the (encrypted) connection strings in config, but with names that include the instance ID. I use a similar method to include a visual cue as to which environment is which on the webpage (e.g. different background colour, and/or a text reminder in top-right of all screens). I was going to include the code to do this but it's the lounge after all. For more, see this tip[^] I wrote a while back. Using it for config strings is exactly the same concept and just as easy.
Of course if you're not running under IIS then you need some other unique environment indicator...
|
|
|
|
|
Hi All,
I said the infamous phrase 'I know a bit about that' at a standup (or sit down, as I always do to be awkward). So that has promoted me to Fibre Optic expert who knows all the connectors, bend radius, data rate and most scary a fusion welder. What I meant was I have used fibre optics in the past for serial data lines and have laid them in existing trunking. They were expecting Autocad designs of trunking that could be built! Warning for new players! 
|
|
|
|
|
Could never happen to me. There is not a snowballs chance in hell that I would volunteer ANY information about what I can an cannot do. That can ONLY lead to more work. 
The only possibilty of hearing me volunteer for something is when the issue has already - irrevocably - been assigned to somebody else!!! 
Anything that is unrelated to elephants is irrelephant
Anonymous
-
The problem with quotes on the internet is that you can never tell if they're genuine
Winston Churchill, 1944
-
Never argue with a fool. Onlookers may not be able to tell the difference.
Mark Twain
|
|
|
|
|
Johnny J. wrote: That can ONLY lead to more work
Or your boss realizing you have value. 
|
|
|
|
|
New contractor trying to make a good impression, with the task I was assigned complete faster than they were thinking...
|
|
|
|
|
Oh my ... a fusion welder ... I can help with that as I had a lot of practice with it while doing some fibre optic research many moons ago. This was fun ... But, Autocad design of trunking is not my cup of tea, I must admit ...
modified 2-Mar-21 9:26am.
|
|
|
|
|
Haven't seen it yet, sounds like a prop from Star Trek, "Scotty, put that Trible down and get the fusion welder"!
|
|
|
|
|
sounds futuristic indeed ...
modified 2-Mar-21 9:44am.
|
|
|
|
|
Where I worked in the late 90s I became the go-to person for custom serial cables.
That's about the limit of my ability to do hardware work.
|
|
|
|
|
|
I have often stated, "a little bit of knowledge can be a dangerous thing." It has a related corollary, "what ever you do, don't admit to having what ever little bit of knowledge you have." That's where the danger comes in as you found out.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
Don't be the person who knows who how to get thing A talking to thing B if you are not on the project, You are hounded to death by other teams, who can't be bothered to read the document you wrote on thing A talking to thing B as they 'just don't have time' to waste (by that reasoning you are merely playing minesweeper and nothing else)  .
|
|
|
|
|
Yes, I've been there too. It's very, very annoying.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
Hear granny's legs the wrong way around? (11)
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
