|
We (our Team) have deceided to apply the XCode comment style for our iOS-code. It provides some tooltip and assistent help.
I learned commenting gets important if different people work with the code.
Press F1 for help or google it.
Greetings from Germany
|
|
|
|
|
I try to use a three-tiered commentary when possible.
There's commentary through the code explaining what something does (that is trivial) and why it does it (particularly if one would not normally do it the way it's being done). Modifications to the original "working" code will also include a date in the comment.
There's a boiler plate on every method I create (or modify if VS creates it) and it will have the creation date stuff and then updates, bugfixes, etc., also with a date for the changes block.
Finally, a separate file (text) which keeps a bit of a narrative in blocks This will of course have a date and, if a version number change is made, it's up there, too. This isn't generally detailed, but will 'name names'.
The last of these is interestingly useful in that the chronology is all in one place and if things go wrong you can go back to see what you did then (and how to blame someone else).
All of these point to the same bottom line: I presume I'll have forgotten all about whatever it is I had done or was thinking if I ever need to go back there. The first person I ask for help is me . . . and comments are the only way I can answer.
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "As far as we know, our computer has never had an undetected error." - Weisert | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
In our team we do not comment the code itself, but add an opening block of comments (where it appropriate) to explain how this code connected to the flow of the application and what the purpose of it...The reason is that we can nor afford single-responsibility and even one is responsible for a certain part of the code it is common that in absence of one someone else will pick up a bug-fix/feature request...
So comments that explain the purpose of some code (without getting in the implementation details) can be very useful...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
The code is there to meet requirements, so you can just add this all over:
|
|
|
|
|
charlieg wrote: but I sure as hell would like to know why....
Yeah, various voices have made noises about comments being unnecessary, not realizing that even well structured code will tell you the what and how but rarely the why.
Marc
|
|
|
|
|
The question is if the "why" should be documented in the code itself.
My opinion is that code should have as few comments as possible.
Good code describes itself (mostly) and bad code probably has bad comments too.
In my experience comments are never good.
Even written a tip about it (with some sad real world examples) 
|
|
|
|
|
Umm, I disagree. Or maybe I want to disagree. Perhaps a programmer's guide of the system (separate document) might cover this. I've got two files here - one with 2300 lines of code and the other with nearly 6000. Maybe it's time to clean things up?
I guess where I'm coming from is that code attacks a problem domain, and without any description of code in the problem domain context, you're likely to go off the rails.
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
The problem (that we as engineers have been struggling with forever) is that there are two representations of the project - the project as planned and the project as delivered. Any separate document describing the plan is certain to get out of sync with the code, as are comments in the code.
The problem is not unique to programming. How many old buildings have updated (and correct) plans filed with the relevant authorities?
If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.
--Winston Churchill
|
|
|
|
|
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
I used to work somewhere that had an automated tool that would deny a code check-in unless the functions were commented. So we used another tool to auto-generate the comments. Things like this always remind of Benjamin from Animal Farm
Quote: Benjamin was the oldest animal on the farm, and the worst tempered. He seldom talked, and when he did, it was usually to make some cynical remark–for instance, he would say that God had given him a tail to keep the flies off, but that he would sooner have had no tail and no flies.
|
|
|
|
|
This morning, while on the bus, I realized that I was the only one reading a real, paper, book...All the other readers used some kind of electronic device...
Does it mean that I'm too old?
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Maybe they read ebook. For example I read a lot of book on my phone
|
|
|
|
|
That's the point - I like the smell and feel of paper books...so I read them in that format and not e(lectronic)book format...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: Does it mean that I'm too old?
Yes, get with the times pops!
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
|
Mike Hankey wrote: pops
The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Found it on YouTube...what an awesome movie, thanks!
Tim Roth is a great actor very versatile, saw him recently in "Lie to me" series and "Rob Roy" the movie.
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
|
Think of it this way: an average Harry Potter book weighs 750g: my tablet weighs 350g
The Rowling classic measures 14 x 21 x 5 cm: my tablet is 12 x 19.5 x 1 cm.
"Harry Potter and the Half-Blood Prince" holds one novel (albeit 607 pages of novel): my tablet currently holds around 400. And it's nowhere near full.
Which would you rather try to slip in a pocket and carry around? 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
You totally missed my post - I was talking about BOOKS...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
You're not alone. I love books. They never need to be charged, their type face is of exceedingly high quality (devices are getting better), and the boot time is excellent (open it). As a kid, I would ride my bike down to the main library in our town and just walk the book stacks.
I plead guilty to being a "pops".
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
My dad was working with the Ministry of Interior - and that meant a lot of privileges in the communist Hungary...One of them was free passage in a special library with hundreds of thousands of books banned from the open libraries...
I was spending half of my summer vacation in that library...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
So, what "banned" material have you been reading?
|
|
|
|
|
Hemingway
Orwell
The hungarian laws against jews in WWII (not really a book, but interesting)
A lot of biography written in the pre-communist are by people disappeared later...
A lot of pulp/fiction written between the two world wars...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
It give a special feeling .. kind of privileged one when you have access to something which other don't have
I can understand problem with Orwell but not sure why anyone would prohibit Hemingway's books
|
|
|
|
|
Hemingway criticised the way the soviet communists done things...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
(By the way I DO read e-books...about technical stuff, but books for entertainment, novels and like, I read in paper format...and I take them from the local library)
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
