 |
|
|
I always defer to my favorite software book Code Complete for these kinds of questions. McConnell spends a whole chapter talking about best practices in writing comments. (This may seem silly to some, but if you read the book, it makes a TON of sense.) Chapter 32 states plainly "Use comments to prepare the reader for what is to follow", and explains the well-established convention of putting comments above the code it's documenting.
Further (and this is the fun part you can show your professor), he claims "This idea isn't always taught in programming classes, but it's a well-established convention in commercial practice."
Well-established conventions, until there is a clear technical reason to do otherwise, should be followed!
Also, there has been some discussion hinting that well-crafted code should not need comments. My thought is all about how fast you can look at code to quickly understand what it's supposed to do. Your brain doesn't waste time translating variable names (even if they're well named), doing math, finding control loop conditions, etc.
Stuart
|
|
|
|
|
|
|
A couple of lines for general explanation above the code block, and short 2 or 3 word comments at the end of appropriate lines to explain what a particular variable or called function is for. Always worked for me.
|
|
|
|
|
|
|
Personally, my comments generally come before the code, but it's because of the way I code. I don't set out to write comments; rather, as I enter a new conceptual block, I find that it helps clear my mind to write a quick explanation of what I'm going to do. Then I find it easier to focus on what needs to be done within the conceptual block. Thus, the comments I write actually direct the code, rather than the other way around.
I don't need to go back over the code and add comments this way. Basically, if there's a comment in the code, it's because it was needed to write the code; if there's not, it's because the conceptual block was straight-forward enough that this guide wasn't necessary for my initial thoughts.
I suppose you could say my coding style is self-commenting. Or is my commenting style self-coding? 
|
|
|
|
|
|
|
Above the code that implements it is best. That allows the reader to go from generalitites to specifics by reading top to bottom, just like an outline, or a story, or any other type of explanatory writing.
I think you should your the entire class to turn in an assignment with the comments below the code they comment. They can't mark down for it since the professor provides examples comemnted that way. If they actually read your source code, they'll probably try to mark it down though.
patbob
|
|
|
|
|
|
|
Now, if only I could sing, this[^] would be the gig to go for.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys | Onyx
|
|
|
|
|
|
|
Just walk this way...
Panic, Chaos, Destruction.
My work here is done.
|
|
|
|
|
|
|
You've always been a bit of a big mouth Vilmos.
"People who don't like their beliefs being laughed at shouldn't have such funny beliefs." ~ Anon
"If you can't explain it simply, you don't understand it well enough" ~ Albert Einstein
Currently reading: 'The Greatest Show on Earth', by Richard Dawkins.
|
|
|
|
|
|
|
Who knows, maybe he is Tyler made for the job.
//L
|
|
|
|
|
|
|
|
|
|
It's good to see you're Back in the Saddle.
//L
|
|
|
|
|
|
|
I can't. I found love in an elevator.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith As Braveheart once said, "You can take our freedom but you'll never take our Hobnobs!" - Martin Hughes.
My blog | My articles | MoXAML PowerToys | Onyx
|
|
|
|
|
|
|
Pete O'Hanlon wrote: I found love in an elevator.
I did that once, but it didn't last. Too many ups and downs. 
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
|
|
|
|
|
|
|
Last time I would walk this way, was because I found love in an elevator.
Silver member by constant and unflinching longevity.
|
|
|
|
|
|
|
"but they hope to continue with a new frontman"
[sarcasm] One imagines that would be a huge success. [\sarcasm]
|
|
|
|
|
|
|
As I'm sure most people have noticed, today is the 11th November, Armistice Day. It has just been 11:00 in the UK, and I stopped to observe the two minutes silence. It occured to me that, at least in my office, I was the only who did.
Does anyone else here stop for two minutes at 11:00, whenever it reaches that time for you? I know we used to do it every year at school, not enforced, but a case of 'if you don't want to observe it, respect those who do', but I've noticed a lot of people don't bother once they've left.
|
|
|
|
|
|
|
As an Ex-Squaddie I always observe it.
------------------------------------
In science, 'fact' can only mean 'confirmed to such a degree that it would be perverse to withhold provisional assent.' I suppose that apples might start to rise tomorrow, but the possibility does not merit equal time in physics classrooms. Stephen J Gould
|
|
|
|
|
|
|
The whole office here stopped for two minutes, whether they would have all done it if there hadn't been an announcement remains unknown.
I always stop for two minutes, like you I used to in school and haven't stopped.
- Rob
|
|
|
|
|
|
|
I admit there wasn't an announcement made here...
|
|
|
|
|
|
|
Incidentally, first armistice day without a WWI Veteran.
They have all gone now, it is history.
------------------------------------
In science, 'fact' can only mean 'confirmed to such a degree that it would be perverse to withhold provisional assent.' I suppose that apples might start to rise tomorrow, but the possibility does not merit equal time in physics classrooms. Stephen J Gould
|
|
|
|
|
|
|
We observed 2 minutes silence at 11:00 in my office, although I could still hear mouse clicks and typing sounds. To be honest, I wouldn't have remembered if my boss hadn't made an announcement.
|
|
|
|
|
|
|
tufkap wrote: although I could still hear mouse clicks and typing sounds
That's where a lump hammer is needed, one swift blow to the fingers should prevent it happening again.
|
|
|
|
|
|
|
I was appalled at the number of people who carried on typing during the silence. We had a signal that it was starting so there was no excuse whatsoever just a complete lack of respect.
|
|
|
|
|
|
|
Company wide silence here. It wasn't announced in our office (the loudspeaker system's bust here), but we knew it was 11am.
Java, Basic, who cares - it's all a bunch of tree-hugging hippy cr*p
|
|
|
|
|
|
|
In Italy we're more inclined to do a similar thing on April 25, as it is the day recognized as the end of combats between the Resistance and nazis/fascists, started a few days earlier in 1945 as a nation-wide insurrection. Actually, it's more like a feast, very much like on June 2, Day of the Republic.
I guess things turned out to be a bit different on the other side. The end of the war was just the beginning of the reconstruction and, basically, a new era altogether for Italy.
You know, I feel somewhat guilty, deep in my person, that my Country participated at such a terrible war on the wrong side (or at all).
|
|
|
|
|
|
|
Dario Solera wrote: You know, I feel somewhat guilty, deep in my person, that my Country participated at such a terrible war on the wrong side (or at all).
I don't think you have any reason to think so - nor, on that hand, do the modern day Germans, but I was told that a lot of them still had thoughts or issues like yours
I personally love your country and the Italian people, and would never ever dream of making a comment like 'well, you were on the wrong side' or such .. ok, I'll admit, we joke amongst ourselves if we're meeting a German 'just dont mention the war' (think that was from a Fawlty Towers episode), and I did make a comment to 'home' when I was in Italy a few weeks ago about Mussolini's influence still being felt in that the trains and ferries (around Lago di Como/Bellagio) still running on time.
(interestingly for me, I drove through the village (Dongo) on the western side of Lago di Como where Mussolini was executed after having been caught with his lover trying to escape to Switzerland)
.. but no, Dario, you cant help what has gone before you, and I dont know anyone who would try to persecute modern day Italians or Germans for it - hopefully we have all learn't and moved on, and maybe the armistice/silence 'lest we forget' will remind people we don't want to go back there (ok, so Im glossing over WWII, Vietnam, IRAQ etc ... )
ciao
Garth
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Rant 
Admin