For anyone who thinks what I produce in commenting my code is trival... well it is not. I put alot of work and time into just thinking about what would be a good name for an asm jmp label or the actual parameter name and name of functions.
I spend a good 10% of my time producing those comments. Now, I actually like putting in my code because it helps me focus on what I'm doing and they are also very useful when I have multi parameter functions.
Plus it makes the code look pretty.
But, I would not expect anyone else to do so if they weren't focused on wooing entry level and·beyond entry level programers (think high school kids).
...
But, I have a dark side when commenting. I believe that comments should only be applied to the objects interface and the code should self comment itself. The user of the code should be able to not understand what's going on under the hood and not have to care. Only the function documentation needs to be laid out and nothing else.
I find in line code comments bad because I usually put them in to explain some hack or work arround that I did. Then latter I fix that and take them out.
ASM is different however because it is not necessarily always readable since even simple stuff like array indexing looks ungodly.
I make of habit of commenting assembly code line-by-line, even if it's not for publication. I simply can't come back to uncommented assebmly code several months hence and have a clue what I was thinking when I wrote it. I didn't always do this, but after awhile it became apparent that doing the commenting when the big picture is fresh saves time in the long run. It's particularly helpful during debugging, because it's much harder to explain away a bug than simply to produce the code for it.
Kye said...
...
For anyone who thinks what I produce in commenting my code is trival... well it is not. I put alot of work and time into just thinking about what would be a good name for an asm jmp label or the actual parameter name and name of functions....
Kye, you are truly a model commenter and I thank you for that. You are a shining example that a great commenter does not have to be mediocre at programming. Keep up the fantastic work.
Now here's something I said in another part of the forum about 15 hours short of exactly one year ago from now:
I said...
I think a big contributing factor to confusion in general is the overall lack of comments on many of the programs (objects). I'm not dumb, and I can learn a lot by example, but I become completely imbecilic sometimes when I try to figure out how some of these objects do what they do. The brilliant minds who write the code for them breeze right through it, like one of those piano masters who can pick up a piece of new music and just start playing. But for people like me, I'm a mechanical type who needs little computers to do things for me so I want to drop in, figure this stuff out, get it up and running, and go on to the next thing. But without comments to show me the way, I'm quickly lost, bogged down, depressed, fed up. The Propeller has a lot of potential, but without really good documentation, it's gonna take a lot longer for people like me to grab onto it and hug it for all it's worth.
At the very least the objects should have a list of what the limits on the variables are. Many times, when faced with what variables are going in or out of an object, it's mind-reading time.
And when it comes to dealing with objects, I feel less and less like an engineer and more and more like a REVERSE engineer...
It's newbie whining, maybe, and nobody here is expecting Noble-prize winning literature in their programs... but even a few comments can go a really long way.
You guys have got to give me credit here. It's been one year since I bellyached about lack of comments in the OBEX. And I'm still here, working on the Prop. You may send money in lieu of cards, flowers and candy. It's something to celebrate, don'tcha think?
CRP said...
Maybe we could have a periodic contest for the "best and clearest commented code" to be voted on by members ? (secret ballot of course to not step on toes or hurt feelings)... and perhaps Ken could award some nice Parallax goodie. Although I'm not ready to post my stuff in the OBEX yet, it would be fun to think there's that possibility. And what happens next? Others look to the winner's code for 'how to do it right' .... good things breed good things around here!
I agree. I'm thinking about submitting some stuff that I've been working on...
As I said above, Kye's code and comments are some of the best I have seen for newbies. Given the modules he has done, I have a feeling for what he's probably doing and I am sure you will be pleasantly surprised when he reveals all. He has warned us it will be commercial, so don't expect it to be free.
Having said that, Kye has posted a number of objects. So beginners, I suggest you take the time to look at them - very nice code with excellent comments.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Links to other interesting threads:
When I learned to program it was on Hollerith cards submitted to a computer weenie behind the counter that would read them into an IBM 360. Even back then the better Proffs taught us how to plan and design large computer programs that went together quickly with the cooperation of a multidisciplinary teams that, in the out years, would be cheap and easy to maintain. If you've ever observed the staff rollover in a military command you can appreciate the standards. Using top-down/bottom up methods yields compact robust code. The embedded systems platform is a haven for the introverted prima-donna type that can have no interest in lowering the level of difficulty for peers. In large companies not commenting is a way to be: hard-to-lay-off. This is so much a part of our life-fabric that TV shows like Big Brother, Survivor et al dominate the nauseating prime time slots. There was a Mars mission that went dead in the water because of a data typing error. You can bet the developers didn't comment their source code. HLLs like Pascal and Ada force data typing like a binary Nazi for just that reason. Un-commented source code is cheap and easy.............but you get what you pay for.
Comments
For anyone who thinks what I produce in commenting my code is trival... well it is not. I put alot of work and time into just thinking about what would be a good name for an asm jmp label or the actual parameter name and name of functions.
I spend a good 10% of my time producing those comments. Now, I actually like putting in my code because it helps me focus on what I'm doing and they are also very useful when I have multi parameter functions.
Plus it makes the code look pretty.
But, I would not expect anyone else to do so if they weren't focused on wooing entry level and·beyond entry level programers (think high school kids).
...
But, I have a dark side when commenting. I believe that comments should only be applied to the objects interface and the code should self comment itself. The user of the code should be able to not understand what's going on under the hood and not have to care. Only the function documentation needs to be laid out and nothing else.
I find in line code comments bad because I usually put them in to explain some hack or work arround that I did. Then latter I fix that and take them out.
ASM is different however because it is not necessarily always readable since even simple stuff like array indexing looks ungodly.
...
My 2 cents.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Nyamekye,
-Phil
Kye, you are truly a model commenter and I thank you for that. You are a shining example that a great commenter does not have to be mediocre at programming. Keep up the fantastic work.
Now here's something I said in another part of the forum about 15 hours short of exactly one year ago from now:
You guys have got to give me credit here. It's been one year since I bellyached about lack of comments in the OBEX. And I'm still here, working on the Prop. You may send money in lieu of cards, flowers and candy. It's something to celebrate, don'tcha think?
I agree. I'm thinking about submitting some stuff that I've been working on...
Having said that, Kye has posted a number of objects. So beginners, I suggest you take the time to look at them - very nice code with excellent comments.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBladeProp, RamBlade, TwinBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: Micros eg Altair, and Terminals eg VT100 (Index) ZiCog (Z80) , MoCog (6809)
· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBladeProp is: www.bluemagic.biz/cluso.htm
So that's that how they discovered water on Mars[noparse]:)[/noparse]
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
For me, the past is not over yet.