6502... LMAO. I agree, unless, somehow I can get a 6809. Aside from Propeller, it's my favorite CPU.
I like tab insert spaces, and like editors that show spaces. Just a hint is fine. With those on, I don't have trouble very often. SPIN made me like white space sensitive languages. Generally, I just sort this, leaving spaces, or complying with the tabs, whichever is the smallest meta task.
Names are a thing I hate coming up with too. Reading all this makes me realize I often use little short names often, when I just shouldn't. @Whit there you go.
How to be better? Communicate. Lots of good stuff in this thread. Nice topic.
Hey, I often have trouble with scope and compartmentalization. What should be it's own routine, procedure, function, and why?
After a few revisions, I get to a place I can maybe feel good about. Is it always that way, or?
It's just not easy to create self-documenting code. For example I could write (in a sort of C/pseudo code):
// Start the motor
motorPort = TRUE
while (1) {
// Check we are at the end stop position
if (endStopPort == TRUE) {
// Stop the motor
motorPort = FALSE
}
}
Crappy example but it makes a point. The former example is what people write. The latter abstracts things away and nicely documents itself. Basically the comments have moved into the actual code.
"real" programmers will reject the latter, it's too verbose, to much typing, besides unless your compiler does a good job the executable is much bigger and slower.
I have done something like that in my Sodor HDL example above. Luckily in that case it does not result in a lot more generated hardware.
Descriptive variable names are important, but the ones that get used in expressions should be short. I hate reading code like the following that runs off the end of the line:
It should be possible to get the sense of the expression in one eyeful, rather than having to scan it repeatedly, wading through the verbiage, just to find the operators.
Partially self taught, some Waite Group books like their Perl Interactive stuff, a course here and there, but no comp Sci degree.
The best way to improve the efficiency of your code may be decided before you start; how you plan and define what you want it to do. The better the road map, the fewer wrong turns. Sort of a measure twice, cut once. As to the rest, commenting, naming conventions, the internet is full of opinions and flame wars regarding "best" and "elegance". That it must meet its purpose and run within certain expectations are hard givens. All else seems to be finding a balance between how and where documentation is done, how long does the code have to be maintained and by whom. So, back to planing the project before actually writing the first line of code. It may have been Tolkien who wrote "shortcuts make long delays"
Heater,
I work with lots of coders that would prefer your latter example. Or something similar. I guess we are all not "real" programmers?
Also, pretty much all modern compilers would compile both of those examples to a similar number of instructions. Short functions almost always inline unless you set options to not do that.
Phil, I use editors with completion features built in so typing out long stuff is trivial, and within reason it's easier to read and comprehend. However, I agree with you that it can go overboard.
I agree with all the comments bout commenting to support that idiot that needs to understand it in 6 months, lol. I frequently set projects aside for a few months, so it is a must for me.
I also strive to be diligent with versioning as I develop. I will save multiple copies of code as I build things up, especially when my project is simply the merging of several other already done projects.
Lastly, as other mentioned, I do flow charts to help me in developing code.
My Reverse Geocache project is a good example of my programming methods.
@Frank, yes! When learning about video tricks, @Eric Ball and I had some good conversations. Sidebar: I really like his code. Like Johnny Mac, it is clear, educational. One gets a bit better for having worked with it.
But I digress...
Yes, think it through. Eric wrote some code, which I ran to test before he got a Propeller. This amazed me. I have always done this for small bits, but not without a machine, some interactions.
The lesson here is simple: take the time to internalize things. I believe doing this is hardest at first, and after being away, which I often am.
When you do that, you get to a place where you can simulate things, and once you do that once, those skills endure. Things solidify.
Hand assemble, write core bits, key loops, data structures, other things using pencil and paper. Look up all you need to do it. The outcome can or only needs to be a few lines. Won't matter. Just do it.
Pays off.
I used to do that on 6502 long ago. Would be in class figuring something out, hoping I could get it assembled so I could type hex codes in and see it run. I still remember all of that vividly. Where I haven't done the internalizing, the good stuff fades. I can tell, and you may ask why, and for me it's time, or importance.
Maybe you also won't always have time or care. But when you do, invest that time.
I like to make it work, then make it work better. Often, I'll then rewrite it with all the things I learned.
As for "the right way."
Good luck with that. Seriously.
and
Make it work, then make it work better, then make it work faster and or smaller. Refactor, rewrite, all apply here.
and
Also, if you want to share, do it unabashedly. Bad code, or crazy code, whatever, is still code. It can still be used, learned from, talked about, and all that. The more you share, the more you learn about all these things and how to better communicate. It's a good thing.
@potatohead - these comments are some of my favorite of yours! They put a finger right on some of my sore and insecure spots. Thanks - really helpful for me.
Okay - as a priest, I feel obliged to make a confession! ;-)
Blast me if you must. Part of what got me thinking about this is programming in BlocklyProp. Since BlocklyProp programming is free of syntax and formatting issues - it has made examine more closely my code logic, order, tightness, and efficiency.
Since much of what I code in BlocklyProp is for the purpose of tutorials - I don't want to "teach" in a way that forms bad habits.
Like many of you have talked about planning code flow and logic - BlocklyProp lets you work on that part of the code in such a pure way - it makes goofy code easy to spot. So, I a working on that aspect of coding particularly.
When I look at the code in "C" - good BlocklyProp code appears more neat and orderly than does sloppy BlocklyProp code. That is kind of amazing when you think about it.
Two questions that could be applied to the same situation, where one tryes to understand the work of other(s), both fitting for the good, and also for the evil.
- What hell was (s)he thinking about, while (s)he was doing that?
- How did (s)he came to that idea, to do this the way (s)he did?
Henrique
P.S. (s) added, to don't be blamed, for not being as inclusive as I need to (wise wife's advice).
Heater, I'm not a real programmer but your latter example is basically the way I code. By factoring functions and choosing descriptive names it makes the whole job of coding easier. As you know in Forth the idea is to extend the language but I would factor your example further and also simplify it like this in Forth:
pub Motor ( on/off -- )
IF motorPort HIGH
BEGIN endStopPort PIN@ UNTIL
THEN
motorPort LOW
;
0 := stop
1 := start
Now there is only one function but we can say "start Motor" or "stop Motor" or even pass a direction and speed to Motor etc (return). One area in Forth where it helps to add comments though is when you are writing in its "virtual machine language", that is all the low level primitives such as DUP OVER SWAP etc But factoring helps me to reduce parameters and therefore stack manipulation to a minimum if I do it right (not always though).
@Whit - The 5Fs of programming, Functionality First, Fancy Features Follow. All the plans of mice and men don't always work out. Although it is good and proper to have a grand plan (what you want, not how you think it should be done), you need to make sure of basic functionality. Top down "mud map", code bottom up foundational functions to build on. With a tested foundation you know that whatever you build on top of that will not require tearing down again because of a bad foundation causing problems or limiting what you need to do. Besides, I like to "play" which is something that you can do when you code bottom up and many times I have found a better and simpler solution in the process before I have become over-committed.
When I worked in the automotive test group at Philips Semiconductors, company policy required us to not just comment the code for each test package, but to also include a separate manual that described (in detail) how each test was performed.
Our automotive project's schedules were typically around six to nine months, start to release. Two weeks of that time was slated for manual development/completion. The set of documentation usually filled two or three, three-inch binders; test diagrams, schematics, source code, descriptions of each test, device-to-device correlation data, etc.
This was serious stuff. One of the assumptions being that sometime in the future, someone may have to revisit the work. And, true to form, someone had to and did.
Me.
One year after the release of a product, I returned to the doc package to resolve some discrepancy that showed up over time.
So I'm perusing the docs that I had so painstakingly assembled, going "WTH were you thinking, Dave?!?"
The point is, no matter how well you think your comments or extraneous documentation may be, you can always do better.
The above is not targeted at the code development aspect. It's meant for for maintenance of said code.
@Whit - The 5Fs of programming, Functionality First, Fancy Features Follow. All the plans of mice and men don't always work out. Although it is good and proper to have a grand plan (what you want, not how you think it should be done), you need to make sure of basic functionality. Top down "mud map", code bottom up foundational functions to build on. With a tested foundation you know that whatever you build on top of that will not require tearing down again because of a bad foundation causing problems or limiting what you need to do. Besides, I like to "play" which is something that you can do when you code bottom up and many times I have found a better and simpler solution in the process before I have become over-committed.
Love this! Great advice...
Reminds of the 5 Ds of Dodgeball - Dodge, Duck, Dip, Dive, and Dodge!
That was my intent. Good! I face some of those insecurities each time I am away from this stuff. Sometimes it's a battle, just life, things, but I love this stuff. Always have. If you do too, let that guide you. It's pure intent, nothing to be worried about at all.
But... you may, as some of us others do, have to remind yourself of that. We are in the midst of some really sharp people. Much wisdom here. And a great culture.
I am also self-taught, and I do sometimes look at old code and say "Why in the world did I do that ???".
Comments helps a lot, but I can't tell you how many times I've seen this:
LET X = 5 ' Make X equal to 5
Avoid this at all costs. Do not document WHAT this the code is doing. Document WHY this code is doing it.
LET X = 5 ' X holds the Port Value, prepare to read from Port 5
Whit, thank's for the most interesting thread in the forum for years. Also for sharing the style-guide.
Self taught me too, started with ZX81 back in early eighties.
My first Spin program (from 2010 and still running, 24 hrs a day) was a single cog program for controlling pre-heated water from he heat-pump into the water heater. No idea on using several cogs because I was too much BS2 inspired. Several temperature sensors were read and several switches were activated in addition to the computing itself.
Now I have to rewrite spin-files I have written because I'm often running out of cogs -there are still new ideas for the projects. And during this rewriting I often find so many strange solutions I've done.
And that's very interesting. You understand you have done some progress in being a programmer when comparing the things you did long time ago with the way you would do it today. Especially if your new, more powerful version also fits in a smaller spin-file.
If I should come with an advice in this thread, always include Version numbers to your application if you often do upgrades to your projects.
Like this:
CON
Version = 12
PUB main
debug.str(string("Firmware Ver: "))
debug.dec(Version)
This always helps me a lot to avoid version confusions!
Not directly targeted at firmware, but in addition to the "Zen of Python" these are some of the things we have found useful to keep in mind when writing scientific software... which isn't a far hop from firmware really, especially the part about naming things and citing sources. https://jrleeman.github.io/ScientificSoftwareMaintenance/
Whit, thank's for the most interesting thread in the forum for years.
Thanks, Moskog! I am a big fan of marking the version/revision of my code - Just to keep myself straight! Once I have the best working version, I go back and delete the old versions and rename the keeper!
I've gotten such great feedback and from so many of programming heroes on the Forums!
@Bean and @Heater - those examples are really helpful.
Attached the old Gold Standard Checklist from Parallax Semiconductor, 2012. It quickly disappeared, and I couldn't find it among the support materials on parallax.com. I've tried to adhere to it in my own coding going forward. I agree with others that consistency is the main thing, no matter what system you choose. I the pattern is different but consistent, you can usually pick it out quickly.
Geo_Leeman, interesting Zen. I too like to have sources cited, for example, when someone pulls a tricky algorithm or concept or snippet out of a forum thread, book, etc., I like to see it cited.
I'm self-taught too, except for a few classes back as an electrical engineering and then biophysics student, never computer science per se. I'm amazed by what "real" programmers can do today but at the same time completely daunted by the complexity of the tools. Embedded, contained, that's my thing.
My variable names except for idx++ and such are getting longer. Short variable names should be unique sequences of letters and be for the most part very local and obvious in function.
Awareness of the traps in the language and in the Prop (or whatever) itself is a big thing, that is, for getting things done efficiently and for troubleshooting. Reference: The Tricks'nTraps that Phil collated back in the day.
I am a big fan of marking the version/revision of my code - Just to keep myself straight! Once I have the best working version, I go back and delete the old versions and rename the keeper!
Yep. Now we are talking software engineering.
The most amazing aid to writing software, even the most simple project, and keeping things straight is using a source code management tool. No more copying files and directories here and there the with different version numbers appended to their names. No more wondering which was the last "good" version and "where did I break things".
Of course I don't mean any old source code management tool. No, I mean git.
Now a days I start every new project with:
$ mkdir projectName
$ cd projectName
$ git init
Then start hacking code in whatever files. Then...
$ git add thisFile thatFile
$ git commit -m "I changed this and that"
Then hack some more...and repeat...
At the end of days and weeks of that, the whole history of everything you ever did is in the git repository. You can time-warp backwards and forwards through versions.
Then, for peace of mind, keep the whole git repository on github.com. Then you can share your efforts with anyone who might be interested. And if your house burns down your code is safe in github.
Best part of it all is that you can totally mess with your code, try experiments, break things, if it does not work out then so what? Just "git checkout" the last version and continue.
I have loathed and hated source code management systems for decades, those complex, clunky, slow tools that companies always insist we use on their projects. I have had to use many.
Git, on the other hand, actually helps you as you hack on code.
I'm a huge fan of git/github - I've even started tracking my PCBs there as the issue tracker is hugely helpful. Just cut a tag when the boards go to production and it's easy to get back there and see what went wrong.
There was also a great sub-disussion on version control and bug tracking as part of best practices on this week's embedded.fm https://www.embedded.fm/episodes/243
@Tracy - thanks for both those resources!
@Heater - I never thought of working git/github the way you describe - I ONLY thought of it a way of working with others. Duh! Great tip!
Comments
I like tab insert spaces, and like editors that show spaces. Just a hint is fine. With those on, I don't have trouble very often. SPIN made me like white space sensitive languages. Generally, I just sort this, leaving spaces, or complying with the tabs, whichever is the smallest meta task.
Names are a thing I hate coming up with too. Reading all this makes me realize I often use little short names often, when I just shouldn't. @Whit there you go.
How to be better? Communicate. Lots of good stuff in this thread. Nice topic.
Hey, I often have trouble with scope and compartmentalization. What should be it's own routine, procedure, function, and why?
After a few revisions, I get to a place I can maybe feel good about. Is it always that way, or?
Thoughts?
I remember that book; or perhaps a whole series of Programming Proverbs.
To me, meaningful names and useful comments are most important.
// Start the motor motorPort = TRUE while (1) { // Check we are at the end stop position if (endStopPort == TRUE) { // Stop the motor motorPort = FALSE } }Or more descriptively:startMotor () { motorPort = TRUE } stopMotor () { motorPort = FALSE } isAtEndStop () { return (endStopPort == TRUE) } startMotor() while (1) { if (isAtEndStop) { stopMotor() } }Crappy example but it makes a point. The former example is what people write. The latter abstracts things away and nicely documents itself. Basically the comments have moved into the actual code.
"real" programmers will reject the latter, it's too verbose, to much typing, besides unless your compiler does a good job the executable is much bigger and slower.
I have done something like that in my Sodor HDL example above. Luckily in that case it does not result in a lot more generated hardware.
It should be possible to get the sense of the expression in one eyeful, rather than having to scan it repeatedly, wading through the verbiage, just to find the operators.
-Phil
The best way to improve the efficiency of your code may be decided before you start; how you plan and define what you want it to do. The better the road map, the fewer wrong turns. Sort of a measure twice, cut once. As to the rest, commenting, naming conventions, the internet is full of opinions and flame wars regarding "best" and "elegance". That it must meet its purpose and run within certain expectations are hard givens. All else seems to be finding a balance between how and where documentation is done, how long does the code have to be maintained and by whom. So, back to planing the project before actually writing the first line of code. It may have been Tolkien who wrote "shortcuts make long delays"
really_long_variable_name := another_really_long_variable_name * yet_another_really_long_variable_name + 50 * moderately_long_name?
Mike
I work with lots of coders that would prefer your latter example. Or something similar. I guess we are all not "real" programmers?
Also, pretty much all modern compilers would compile both of those examples to a similar number of instructions. Short functions almost always inline unless you set options to not do that.
Phil, I use editors with completion features built in so typing out long stuff is trivial, and within reason it's easier to read and comprehend. However, I agree with you that it can go overboard.
The Software Developers Sourcebook (1985) - It's on the right side of the first row.
http://www.bombjack.org/generic/generic-books-applications.htm
I also strive to be diligent with versioning as I develop. I will save multiple copies of code as I build things up, especially when my project is simply the merging of several other already done projects.
Lastly, as other mentioned, I do flow charts to help me in developing code.
My Reverse Geocache project is a good example of my programming methods.
I guess since I am self-taught, I always wonder if someone else looks at my code, they may say, "what was he thinking!?!?!?"
But I digress...
Yes, think it through. Eric wrote some code, which I ran to test before he got a Propeller. This amazed me. I have always done this for small bits, but not without a machine, some interactions.
The lesson here is simple: take the time to internalize things. I believe doing this is hardest at first, and after being away, which I often am.
When you do that, you get to a place where you can simulate things, and once you do that once, those skills endure. Things solidify.
Hand assemble, write core bits, key loops, data structures, other things using pencil and paper. Look up all you need to do it. The outcome can or only needs to be a few lines. Won't matter. Just do it.
Pays off.
I used to do that on 6502 long ago. Would be in class figuring something out, hoping I could get it assembled so I could type hex codes in and see it run. I still remember all of that vividly. Where I haven't done the internalizing, the good stuff fades. I can tell, and you may ask why, and for me it's time, or importance.
Maybe you also won't always have time or care. But when you do, invest that time.
Oh yeah. They can, will, do. Its OK.
@potatohead - these comments are some of my favorite of yours! They put a finger right on some of my sore and insecure spots. Thanks - really helpful for me.
Blast me if you must. Part of what got me thinking about this is programming in BlocklyProp. Since BlocklyProp programming is free of syntax and formatting issues - it has made examine more closely my code logic, order, tightness, and efficiency.
Since much of what I code in BlocklyProp is for the purpose of tutorials - I don't want to "teach" in a way that forms bad habits.
Like many of you have talked about planning code flow and logic - BlocklyProp lets you work on that part of the code in such a pure way - it makes goofy code easy to spot. So, I a working on that aspect of coding particularly.
When I look at the code in "C" - good BlocklyProp code appears more neat and orderly than does sloppy BlocklyProp code. That is kind of amazing when you think about it.
Two questions that could be applied to the same situation, where one tryes to understand the work of other(s), both fitting for the good, and also for the evil.
- What hell was (s)he thinking about, while (s)he was doing that?
- How did (s)he came to that idea, to do this the way (s)he did?
Henrique
P.S. (s) added, to don't be blamed, for not being as inclusive as I need to (wise wife's advice).
pub Motor ( on/off -- ) IF motorPort HIGH BEGIN endStopPort PIN@ UNTIL THEN motorPort LOW ; 0 := stop 1 := startNow there is only one function but we can say "start Motor" or "stop Motor" or even pass a direction and speed to Motor etc (return). One area in Forth where it helps to add comments though is when you are writing in its "virtual machine language", that is all the low level primitives such as DUP OVER SWAP etc@Whit - The 5Fs of programming, Functionality First, Fancy Features Follow. All the plans of mice and men don't always work out. Although it is good and proper to have a grand plan (what you want, not how you think it should be done), you need to make sure of basic functionality. Top down "mud map", code bottom up foundational functions to build on. With a tested foundation you know that whatever you build on top of that will not require tearing down again because of a bad foundation causing problems or limiting what you need to do. Besides, I like to "play" which is something that you can do when you code bottom up and many times I have found a better and simpler solution in the process before I have become over-committed.
Our automotive project's schedules were typically around six to nine months, start to release. Two weeks of that time was slated for manual development/completion. The set of documentation usually filled two or three, three-inch binders; test diagrams, schematics, source code, descriptions of each test, device-to-device correlation data, etc.
This was serious stuff. One of the assumptions being that sometime in the future, someone may have to revisit the work. And, true to form, someone had to and did.
Me.
One year after the release of a product, I returned to the doc package to resolve some discrepancy that showed up over time.
So I'm perusing the docs that I had so painstakingly assembled, going "WTH were you thinking, Dave?!?"
The point is, no matter how well you think your comments or extraneous documentation may be, you can always do better.
The above is not targeted at the code development aspect. It's meant for for maintenance of said code.
Regards,
DJ
Love this! Great advice...
Reminds of the 5 Ds of Dodgeball - Dodge, Duck, Dip, Dive, and Dodge!
That was my intent. Good! I face some of those insecurities each time I am away from this stuff. Sometimes it's a battle, just life, things, but I love this stuff. Always have. If you do too, let that guide you. It's pure intent, nothing to be worried about at all.
But... you may, as some of us others do, have to remind yourself of that. We are in the midst of some really sharp people. Much wisdom here. And a great culture.
Comments helps a lot, but I can't tell you how many times I've seen this:
LET X = 5 ' Make X equal to 5
Avoid this at all costs. Do not document WHAT this the code is doing. Document WHY this code is doing it.
LET X = 5 ' X holds the Port Value, prepare to read from Port 5
Bean
Might as well write:
LET X = 5 'Let X = 5
But why X? If it's a port why not say so:
LET port = 5
If it's a port you read from, one of many, why not:
LET inputPort = 5
Which pretty much makes the comment redundant.
Self taught me too, started with ZX81 back in early eighties.
My first Spin program (from 2010 and still running, 24 hrs a day) was a single cog program for controlling pre-heated water from he heat-pump into the water heater. No idea on using several cogs because I was too much BS2 inspired. Several temperature sensors were read and several switches were activated in addition to the computing itself.
Now I have to rewrite spin-files I have written because I'm often running out of cogs -there are still new ideas for the projects. And during this rewriting I often find so many strange solutions I've done.
And that's very interesting. You understand you have done some progress in being a programmer when comparing the things you did long time ago with the way you would do it today. Especially if your new, more powerful version also fits in a smaller spin-file.
If I should come with an advice in this thread, always include Version numbers to your application if you often do upgrades to your projects.
Like this:
CON Version = 12 PUB main debug.str(string("Firmware Ver: ")) debug.dec(Version)This always helps me a lot to avoid version confusions!
Thanks, Moskog! I am a big fan of marking the version/revision of my code - Just to keep myself straight! Once I have the best working version, I go back and delete the old versions and rename the keeper!
I've gotten such great feedback and from so many of programming heroes on the Forums!
@Bean and @Heater - those examples are really helpful.
Geo_Leeman, interesting Zen. I too like to have sources cited, for example, when someone pulls a tricky algorithm or concept or snippet out of a forum thread, book, etc., I like to see it cited.
I'm self-taught too, except for a few classes back as an electrical engineering and then biophysics student, never computer science per se. I'm amazed by what "real" programmers can do today but at the same time completely daunted by the complexity of the tools. Embedded, contained, that's my thing.
My variable names except for idx++ and such are getting longer. Short variable names should be unique sequences of letters and be for the most part very local and obvious in function.
The most amazing aid to writing software, even the most simple project, and keeping things straight is using a source code management tool. No more copying files and directories here and there the with different version numbers appended to their names. No more wondering which was the last "good" version and "where did I break things".
Of course I don't mean any old source code management tool. No, I mean git.
Now a days I start every new project with:
$ mkdir projectName
$ cd projectName
$ git init
Then start hacking code in whatever files. Then...
$ git add thisFile thatFile
$ git commit -m "I changed this and that"
Then hack some more...and repeat...
At the end of days and weeks of that, the whole history of everything you ever did is in the git repository. You can time-warp backwards and forwards through versions.
Then, for peace of mind, keep the whole git repository on github.com. Then you can share your efforts with anyone who might be interested. And if your house burns down your code is safe in github.
Best part of it all is that you can totally mess with your code, try experiments, break things, if it does not work out then so what? Just "git checkout" the last version and continue.
I have loathed and hated source code management systems for decades, those complex, clunky, slow tools that companies always insist we use on their projects. I have had to use many.
Git, on the other hand, actually helps you as you hack on code.
There was also a great sub-disussion on version control and bug tracking as part of best practices on this week's embedded.fm https://www.embedded.fm/episodes/243
@Heater - I never thought of working git/github the way you describe - I ONLY thought of it a way of working with others. Duh! Great tip!