|
If your comments do not fill at least one third of your code, copy & paste until it does!
|
|
|
|
|
We actually had such a rule.
Our automated build system would keep giving us errors "At least 25% of a file must be comments." 
After some insistence from my part they disabled that rule 
|
|
|
|
|
Being a rather elderly gentleman, I am very religious in my documentation. I know I will be maintaining my own code and will not remember why I did something. Most of my documentation is the "why" I did something or "how" it works, but occasionally I justify to myself why a particular construct or pathway was chosen. My code is self-documenting as far as it can be, but comments still give me quicker access to the areas that need modified/added. In addition, since the compiler doesn't care about whitespace, I use it systematically to separate blocks of code or related groups of commands from the rest.
Now when it comes to resources, I will use whatever the language supplies with the only limitations being running efficiently and being easy to read. I am as likely to use a generic list as I am a hash table depending on what is required.
|
|
|
|
|
Congratulations on successfully disabling the rule!
|
|
|
|
|
I don't like the way it is phrased.
If you phrase it: "At least 25% of the lines should be explained by a comment", then I agree. Leaving more than 75% as "self explanatory" is very costly, five years later.
I am very fond of end-of-line comments; they can be made short, to the point, and at the right place. If you need something between the software architecture documentation (I often describe "software architecture" as "the structures that will remain the same if you reimplement the system in a different programming language"), a comment block may apply to, say, an entire function, or at least the core part of it.
From the moment you compile a source file for the first time and three weeks thereafter, any code is "self explanatory". After two years, not even the code written by yourself qualifies. A classic: Geek & Poke[^]
|
|
|
|
|
Depends, most of the code is just properties, setting, getting, some database queries, standard stuff.
I always get a little sad when I see comments like:
someVar = someVal;
foreach (Product p in products)
customer.Save();
product.Save(); Unfortunately, I've only seen comments like that.
And because of these kind of comments I came to detest them.
You may think I'm overreacting, but those are actual real-life comments I see almost daily.
I have 7 years of experience and I have yet to find a single comment that is actually helpful.
I rarely comment my code, maybe once or twice when there were some weird side-effects (which is just bad code).
I'm at the point that I prefer my code uncommented (especially when it's bad code, people who write bad code also write bad comments).
Yeah, comments can't be done right.
|
|
|
|
|
Have you been reviewing your own code years later?
At the beginning I was like you, but then I started having to upgrade my own code... I ended writing comments where needed
note: I say where needed, not overall. But... if not sure, the default is... comment, better one too much than one too few.
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Yes, I did.
And I've always been able to follow it (and my memory concerning code is really bad, most of the time I can't even remember writing it, let alone what it does)
Nothing you can say or do will make me change my mind on comments.
They do more harm than good.
I've written a little tip about comments some years ago: Write comments that matter[^]
It shows that I'm not completely against comments, but use them sparse and wise 
|
|
|
|
|
Sander Rossel wrote: Nothing you can say or do will make me change my mind on comments.
I am not trying to convince you. I am just giving another point of view related to your message.
Sander Rossel wrote: And I've always been able to follow it
I forgot to say: I have been programming in AWL/LAD for PLCs a quite similar language to assembly. There is a bit more difficult make code "self explanatory" and sometimes the names for the variables are coming from electrical engineer / customer...
Sander Rossel wrote: t shows that I'm not completely against comments, but use them sparse and wise
That's exactly the point. And I agree with you, obvious comments just make the program unnecessarily longer and uncomfortable to read
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Nelek wrote: AWL/LAD for PLCs a quite similar language to assembly
I'd comment the hell out of that! 
|
|
|
|
|
When students learn their first programming, and hopefully good programming habits, the big issue is learning the craft of programming, not the complexities of the problem solution they are set to program. So the problem solution is usually fairly simple, down to trivial. So simple that the code line says it all. The professor requires is to comment the code, but what should I write? Isn't it obvious, doesn't the code line tell? - that is common reaction from students.
You don't need comments until the problem solution is getting more complex than you can handle in the first programming course (and second, and third). The problem is so simple that the code IS obvious, and students get into the habit of writing obvious information into the comments. When they later in life get into really huge and composite data structures, intricate execution logic and complex interfaces, they are not into the habit of identifying the non-obvious, only the obvious.
When I teach people programming, I give them one rule regarding comments: Don't waste comments on what the code does, but on why it does it. Of course some students rephrased the "what" part, and I remarked: Sure, you said so in the code statement. Now tell me why you did it! - and usually, they were able to come up with a "why". That's what comments are for.
|
|
|
|
|
It's my fundamental issue with Literate programming - Wikipedia[^], it assumes programmer's have basic literacy.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
Sander Rossel wrote: Once had an issue with a rather unstable connection that often made it fail the first time.
This reminds me of a funny story where a customer kept having intermittent issues with our software...database connections kept timing out. 
Every time the guy would call having problems, I would remote in, and the problem wouldn't happen. Luckily, they were within driving distance, so I went onsite to try and sort it out.
The end user's office was across the driveway to a shipping dock and warehouse. The database server was located in the warehouse office, and the network connection between the two offices was a p2p (line of sight) wireless setup. (apparently a short term solution while they were constructing new offices) When I arrived, there wasn't a lot going on...the software worked without fail. After a while, a truck arrived and began backing into the dock...and suddenly, the database connection was gone! 
For weeks, the customer never made the 'connection'! Luckily, the fix was simply raising the p2p units by a few more feet.
"Go forth into the source" - Neal Morse
|
|
|
|
|
Customers do that 
I have a similar story with a printer.
The user pressed the print button to print somewhere around 100 to 150 invoices.
It often happened that the printing stopped after 50 or so invoices.
And always at the end of the day (because that's when they printed invoices).
So I was testing my software, looking for bugs, writing "fixes" for "what could be it", added additional logging, everything, but I was never able to find the problem.
And when I visited it didn't happen, of course.
This went on for weeks.
Then my manager visited them, for completely unrelated business, and called me "Is that print problem fixed already? I'm about to leave, but they're going to print invoices so I can check on them now."
He checked and you'll never believe what their issue was.
They clicked the print button and SHUT DOWN THEIR COMPUTER TO GO HOME!!!   
Never did it occur to them that shutting down the computer would stop it from printing.
I can tell you I felt like driving a truck over their computers!
|
|
|
|
|
True story.
Some users seems to assume that printers have internal memory which would keep our queued documents.
This assumption comes from a fact that printer keeps printing even when they closed our software.
They don't know that these queued documents are stored on operating system's printer spooler service.
Some colleagues once asked me, why did her printer stop printing? I who was in the middle of serious work mode, glanced over at her desk and yelled, you turned off your computer, that's why!
|
|
|
|
|
We have a networked printer that very much does have an internal queue, so different people may have had different experiences.
(At first I found it unsettling, as jobs disappeared from the queue on my PC almost immediately every time).
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
My very first paid job was working with a mainframe at British Rail, in the 1970s. We used a TSO (Time Sharing System) and a few terminals in a dedicated room. I had a train to catch home so usually was one of the first to leave. Very often the next morning I'd find my colleagues scratching their heads - seems the mainframe had crashed the previous evening. This happened pretty much every day for a couple of weeks. Eventually I came in late one day (train delayed) and my boss had noticed my terminal was powered off. How or why turning off the terminal crashed the mainframe I never understood, but crash it it did. If only they'd told me, a keen young "Energy Studies" student eager to not waste electricity...
At that job too we received mag.tape data, sent up from HQ in London. Usually it arrived fine, but on occasions all the data was wiped. This was at the Railway Technical Centre at Derby where all sorts of testing went on. Turns out the tapes came up, for convenience, on one of the test trains, right into the RTC, and on some days the coaches were shunted onto one of the tracks they were doing overhead power line testing... oops.
|
|
|
|
|
Probably not much help when a parachute does that.
Arguing with a woman is like reading the Software License Agreement. In the end, you ignore everything and click "I agree".
Anonymous
|
|
|
|
|
If "try again!" always was silly coding practice, the the concept of "busy waiting" would not be known. Busy waiting does have its place, especially in embedded systems where the processor has nothing else to do.
Another situation is where several activities are competing for the same resource, but they hold the resource comparatively briefly. As long as you can modify all the competitors, you could program the queueing mechanism, where a process trying to access a busy resource is sent to sleep in a queue and woken up when it gets its turn. Often you can only modify some of the competitors. The effort of implementing a queue mechanism may be high. If the risk of collision is small, it simply doesn't pay.
I have fairly recently programmed a couple "try again" cases: On a quite heavily loaded file system, the number of exceptions due to confliciting accesses was higher than desired. So, when making modifications to a set of files, I make one try for each. Those failing are put into a list for retrying, and a second attempt is made once the first round was completed. Only after a second try, the user is notified. We went from too many access collisions to almost none. Sometimes, the second try came too fast, and the file was still busy. So I added a 5 ms sleep before starting a second round, and after that I haven't seen a single collision.
This "try again" code is next to trivial, and it does solve a real problem. So I cannot agree that the strategy is silly in every case. Sometimes it makes perfect sense.
|
|
|
|
|
Member 7989122 wrote: So I cannot agree that the strategy is silly in every case. Sometimes it makes perfect sense.
 Great examples but not quite the same as the OP where it doesn't make sense to try the same command again right away.
This also brought to mind a program I have to migrate database objects...those having a dependency yet to be created fail and get put into a recursive 'try again' queue. 
"Go forth into the source" - Neal Morse
|
|
|
|
|
Member 7989122 wrote: I have fairly recently programmed a couple "try again" cases: On a quite heavily loaded file system, the number of exceptions due to confliciting accesses was higher than desired. So, when making modifications to a set of files, I make one try for each. Those failing are put into a list for retrying, and a second attempt is made once the first round was completed. Only after a second try, the user is notified. We went from too many access collisions to almost none. Sometimes, the second try came too fast, and the file was still busy. So I added a 5 ms sleep before starting a second round, and after that I haven't seen a single collision.
So, you just assumed that whoever/whatever else had been writing to the file had been doing nothing worthwhile? Personally, if I detect any changes to a file I would avoid writing to it, and notify the user. Better still, open it for exclusive write.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
|
Try try until you succeed !!!
Caveat Emptor.
"Progress doesn't come from early risers – progress is made by lazy men looking for easier ways to do things." Lazarus Long
|
|
|
|
|
DM's Esoteric Programming Languages - Petrovich[^]
What.
The.
F***.
Was.
That.
Guy.
Smoking?
What do you get when you cross a joke with a rhetorical question?
The metaphorical solid rear-end expulsions have impacted the metaphorical motorized bladed rotating air movement mechanism.
Do questions with multiple question marks annoy you???
|
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
