Forum Update - Announcement about May 10th, 2018 update and your password.

Becoming a Better Programmer

WhitWhit Posts: 3,834
All,

As a self-taught programmer for my hobby projects, I've developed the ability (most of the time) to figure out something - code wise - that works. But I am never sure if there is a better or simpler way of doing the same thing - "the right way."

What I would like to learn now is how to be more efficient, more elegant, and how to produce code that is considered "good form." I can work in BASIC, PBASIC, Spin, and have a very elementary understanding of C. I know that time and more experience always help, but I would also like some theory, rules of thumb, or instruction.

Looking at well-written code always impresses me so much and I learn new tricks that way, but I wish I could be a little more systematic in this study.

Any legitimate short-cuts, tips, or suggestions would be appreciated! Till then I will keep hacking away at it...
Whit+

"We keep moving forward, opening new doors, and doing new things, because we're curious and curiosity keeps leading us down new paths." - Walt Disney
«134

Comments

  • 117 Comments sorted by Date Added Votes
  • Whit,

    Like you, I'm mostly a self-taught programmer. I think the thing that has helped me the most is never being afraid to start completely over on a coding project if I think of a better way to restructure the solution. When I'm in a hole, I just quite digging, climb out, and begin anew. I've learned more from my mistakes than any instruction could ever have taught me.

    -Phil
    “Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away. -Antoine de Saint-Exupery
  • I think it's a constant fine tuning evolution.

    I write lots of code lately with my current job, and If at any time there needs to be a change in code I need to be able to address it quickly. I'm big into state machines and perhaps I am old school that way but generally when I plan out my code I create a flow chart. My flow charts are constructed in a way that each node is a "fall through" in it's own right and each node has it's own index or address. The nodes control which index is assigned based on the flowchart condition or event, and a dispatcher of sorts jumps to the currently active node. This fall through-dispatching method allows for other state machines to be introduced and run independently because they would have their own independent index counter and dispatcher.

    The main point is being able to wrap you head around the code and find where you are or where you need to be in code relatively easily.

    A current project I am working on has several different programming areas that at any time need to be changed or modified.

    - R&D stage Schematic and PCB development ... Program and circuit design proof of concept
    - The main board has a PIC micro programmed in pure assembly
    - The touch screen display has it's own native code that needs to communicate bidirectionally with the PIC micro (flawlessly)
    - The images used in the display need to be created somehow and compiled into a native display friendly format
    - The SD card used in the display must be properly formatted and contain the necessary image deck(s) to work with the display program
    - There is also the real world mechanical aspect of driving motors, relays, SSR's, light's, reading sensors, etc.

    ... This is just one project, the same scenario is true for any other project, since the company is migrating many of their machines to touch screen displays.

    Each machine has a different operation and a different set of code instructions. Good programming techniques allow you to switch gears from one project to another efficiently.

    ...and yes, I am also self taught.






    Beau Schwabe -- Submicron Forensic Engineer
    www.Kit-Start.com - bschwabe@Kit-Start.com ෴෴ www.BScircuitDesigns.com - icbeau@bscircuitdesigns.com ෴෴

    Seriously at this point in the game "the ship has sailed" and "I have no expectations" <- said two brothers we ALL know
  • ercoerco Posts: 19,040
    Agreed, self-taught here. I'm not one to pore over someone else's code, I prefer to strike out on my own, per PhiPi. The only exception I can think of is when I was reading encoders fast with a BS2 and someone shared a tight little routine that was fast & elegant.

    I'm atypical, I like the shortest most compact code possible, with plenty of comments . I don't usually name pins, or name variables with SYMBOL. Internal variable names B0, W2 and HIGH 5 are more readable to me. Not the best for sharing with others though. Sometimes when I'm writing code for a magazine article I'll conform a bit.

    I'm weird that way. Of course this flaunts convention and flies in the face of Parallax's own fine recommendations at https://www.parallax.com/go/PBASICHelp/Content/LanguageTopics/Reference/ElementsStyle.htm

    Be verbose when naming constants, variables and program labels. The compiler will allow names up to 32 characters long. Using meaningful names will reduce the number of comments and make your programs easier to read, debug and maintain.

    "When you make a thing, a thing that is new, it is so complicated making it that it is bound to be ugly. But those that make it after you, they don’t have to worry about making it. And they can make it pretty, and so everybody can like it when others make it after you."

    - Pablo Picasso
  • Jeff HaasJeff Haas Posts: 284
    edited April 29 Vote Up0Vote Down
    As a computer science professor said, "When I write code, I do it so that in 6 months from now, some idiot has to be able to read the code and make sense of it. Usually, I'm that idiot."
    San Mateo, CA
  • I'm another self-taught programmer. To the above, I would add:

    * Comments, comments and more comments - sometimes as much as there is code.
    * If you find you are writing similar code several times, consider re-working it to use a subroutine, even if it has to have arguments to cope with variations.
    * Use 'meaningful' names for subroutines, e.g, CreateFile so code reads something like IF A ==B THEN CreateFile
    * I've fallen into the habit of prefixing variables with their type, e.g, intCounter1, fltTemp, boolState
    * I declare lots of constants with meaningful names, e.g. notLit = 0; isLit = 1, or switchPos1 = 1; switchPos2 = 2, etc., allowing me to write something like IF switchPosition == switchPos1 THEN...
    * Look at other people's code and 'borrow' any approaches or techniques that help.
    South Saxons - "we wunt be druv".
  • Hugh wrote: »
    Comments, comments and more comments - sometimes as much as there is code.

    A friend of mine posted a picture on facebook of the stack of paper that represented the code for the Apollo Guidance Computer, which was about 6' tall. Since the AGC only had room for 36 Kwords of ROM and 4 Kwords of writable storage, that ~16K pages of code only had a maximum average of about 2-1/2 lines of code per page, leaving *lots* of room for comments ! Perhaps we can learn something from NASA.

    As a side note, we have increased storage density by a factor of nearly 1 trillion (10^12; I'm not British !) since then (the 72KB ROM was 1 ft3, and the 8KB RAM was 2 ft3).

  • Whit

    Another self-taught programmer here...

    In my opinion, the three most important items for becoming a better programmer are sizing variables appropriately, commenting the code you have written, and using established or distinguishable naming conventions for your variables and functions.

    Concerning variables, if you only need a byte to hold data, then use a byte to hold that data. In other words, do not use a long to hold a bytes worth of data, unless you have a very specific reason for doing so.

    When it pertains to comments, I like to document items of importance, the flow of a program or thread, and code that is hard to comprehend.

    Naming conventions on the other hand, are always open for debate, and are often chosen to suit the needs of an individual programmer and his style of writing, but it is wise to adapt a generally well accepted naming convention, if you will be writing code for someone else or if someone else will be reviewing your code.

    A little over six years ago, Parallax made a small push for Gold Standard Objects for the OBEX, which lost steam as quickly as it developed. The idea was a good one, but due to lack of community support, it fell to the way side.

    Anyhow... there was a thread pertaining Gold Standard Objects, in which I discussed naming conventions for variables and functions. There are likely to be some folks that would disagree with what I wrote, but the concept of naming convention is discussed and you should be aware of naming conventions, if you want to become a better programmer. For further discussion, refer to: https://forums.parallax.com/discussion/137491/gold-standard-objects-up-for-commission/p2

    Additionally, there are two trains of thought pertaining to naming conventions, which is to name everything as short as possible, in order to be more productive (faster writing of code) or being verbose, in order to make it easier to read and comprehend (slower writing of code). I personally prefer code that is verbose, but that is just me.

    For example

    I prefer nStepIndex++ as compared to stpIdx++.


    Novel Solutions - http://www.novelsolutionsonline.com/ - Machinery Design • - • Product Development
    "Necessity is the mother of invention." - Author unknown.

  • WhitWhit Posts: 3,834
    edited April 29 Vote Up0Vote Down
    Thanks for the wonderful comments - ALL!

    I guess the best way to build a better mousetrap is to keep building mousetraps...

    @idbruce and @erco - thanks for the links and the reminder that there is a lot of great advice on these forums and in Parallax resources. I need to go back and look around.
    Whit+

    "We keep moving forward, opening new doors, and doing new things, because we're curious and curiosity keeps leading us down new paths." - Walt Disney
  • Heater.Heater. Posts: 20,698
    edited April 29 Vote Up0Vote Down
    altosack,
    A friend of mine posted a picture on facebook of the stack of paper that represented the code for the Apollo Guidance Computer, which was about 6' tall. Since the AGC only had room for 36 Kwords of ROM and 4 Kwords of writable storage, that ~16K pages of code only had a maximum average of about 2-1/2 lines of code per page, leaving *lots* of room for comments !
    That is the famous Margaret Hamilton and you mean this picture:

    800px-Margaret_Hamilton_-_restoration.jpg

    Don't believe everything you read on Facebook. Certainly don't jump to any wild conclusions from it, like 2.5 lines of code per page or voting for Trump.

    I have long suspected there is something bogus about the claims made about that picture.

    Today we can find out. We can download the original AGC source code and check: https://github.com/chrislgarry/Apollo-11

    In there I find a total of 130667 lines in the assembler source code files.
    There are 34256 lines of purley comment (Starting with "#").
    There are 14763 blank lines.

    That means there is only 81648 lines of source text.

    The ratio of comment lines to source lines is about 40%.

    Now: Old computer line printer paper, as in the famous Hamilton picture, has 60 lines per page, if I remember correctly. So printing out the entire AGC source would amount to 130667 / 60 = 2177 pages.

    That is less than the 2500 pages in a box of regular printer paper today, which is less than a foot high, about 25cm or 10 inches.

    So what is all the rest of that stack of paper? Well, I guess there were a few AGC versions, for different missions. They might have included test code and so on.

    Also, assuming one machine instruction word is generated by one assembler instruction then we ain't going to fit 81648 instruction words in the 36Kword memory. But, as far as I can tell that source code repository holds both the code for the Command Module AGC and the Lander AGC. So only about 40 thousand lines of code each. Not all source lines generate code, they are literal definitions and so on. So, I think this all adds up.

    Anyway, poking around in AGC source I'd say it looks pretty good. Almost every line carries some useful comment about what and why it is there.

    In my experience of working on projects were the 8080/86 assembler source is a stack of paper only 10 inches high things can become very non-trivial to even find!

  • @phil - Your signature quote says it all, "“Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." -Antoine de Saint-Exupery

    Many of you point toward this idea!
    Whit+

    "We keep moving forward, opening new doors, and doing new things, because we're curious and curiosity keeps leading us down new paths." - Walt Disney
  • Heater.Heater. Posts: 20,698
    edited April 29 Vote Up0Vote Down
    Not me. Antoine de Saint-Exupery may be correct in narrow sense.

    On the other hand:

    "Perfection is the enemy of the good"
    - Voltaire

    "Were it not sinful then, striving to mend,
    To mar the subject that before was well?"
    - Shakespeare

    (Or "If it ain't broke don't fix it")

    We should not strive for perfection. It's unattainable, hence depressing when you don't get there. It's expensive. It's time consuming. Before you get done everyone will have lost interest, including yourself.

    Yes, I'm sometimes guilty of perfection hunting. Tweaking code formatting, tinkering with variable/symbol names, refactoring this and that. Then realizing the whole approach is dumb and start doing it over. It's a ridiculous life sucking loop of despair....

    Then there are the bridge designers who remove everything they can, on reaching perfection the bridge collapses. See recent Florida incident.
  • WhitWhit Posts: 3,834
    edited April 29 Vote Up0Vote Down
    By the way, it is very encouraging to me to see how many of you are self-taught.

    My first programs were written on an Apple ][ and a TRS 80 Pocket Computer.

    My most used program on the TRS 80 Pocket Computer added feet, inches, and fractions. My Dad and I - both architects - used it until calculators became available for that function. You can get one now for less than $15.
    Whit+

    "We keep moving forward, opening new doors, and doing new things, because we're curious and curiosity keeps leading us down new paths." - Walt Disney
  • Whit wrote: »
    By the way, it is very encouraging to me to see how many of you are self-taught.

    My first programs were written on an Apple ][ and a TRS 80 Pocket Computer.
    I started off being self-taught but late in my career ended up getting a degree in computer science. In fact, I didn't really learn that much getting the degree. I just did it so I wouldn't be the only one in my family without one! :-)

    My first programs were on a Monrobot XI, an IBM 1620, and then on a DEC PDP-12. I guess I must be a bit older than you are.

  • Don't miss my post above Whit.

    I had to get into programming via an actual course (A Level Computer Science) because there were no computers around at the time. That was only introductory, BASIC and some assembler. Most of the course was other things, numerical analysis, statistics, computer architecture.

    Everything else I had to pick up on the job as best I could. Sadly I was just that bit too old to be a teenager with an C64 or such.
  • idbruceidbruce Posts: 5,640
    edited April 29 Vote Up0Vote Down
    Whit

    Over the years, I have examined a lot of code written by other people. It is noteworthy to say that some of the best and most interesting code that I have ever examined, was poorly documented, lacked proper naming conventions, and was generally very difficult to get a grasp of what was occurring during run-time, unless of course by stepping through the program with a debugger. :)

    There have been many times, that I would rewrite someone else's programs with comments and proper naming conventions, just to get a better handle on program flow, for alteration purposes.

    Brilliant code can often be the most difficult code to read, because the brilliant programmer that wrote it was to lazy to make it neat or understandable to others :) Just remember that programming brilliance doesn't require naming conventions or documentation :)

    I suppose a person could say that just because code appears to have been written by an amateur, doesn't mean that it actually wasn't written by a well seasoned professional programmer :)


    Novel Solutions - http://www.novelsolutionsonline.com/ - Machinery Design • - • Product Development
    "Necessity is the mother of invention." - Author unknown.

  • @Heater - Thanks. Good points.

    I also had a Timex Sinclair PC and a C64.

    Here is another walk down memory lane!

    Whit+

    "We keep moving forward, opening new doors, and doing new things, because we're curious and curiosity keeps leading us down new paths." - Walt Disney
  • Heater. wrote: »
    Don't miss my post above Whit.

    I had to get into programming via an actual course (A Level Computer Science) because there were no computers around at the time. That was only introductory, BASIC and some assembler. Most of the course was other things, numerical analysis, statistics, computer architecture.

    Everything else I had to pick up on the job as best I could. Sadly I was just that bit too old to be a teenager with an C64 or such.
    Heater. wrote: »
    Don't miss my post above Whit.

    I had to get into programming via an actual course (A Level Computer Science) because there were no computers around at the time. That was only introductory, BASIC and some assembler. Most of the course was other things, numerical analysis, statistics, computer architecture.

    Everything else I had to pick up on the job as best I could. Sadly I was just that bit too old to be a teenager with an C64 or such.
    When I first started getting interested in computers there also were none around that I had access to. However, my step father worked for GE and brought home some training materials they gave to their employees along with a lot of random parts, mostly relays. I ended up using the information from the books to build some simple computer circuits using the relays. I had a 4 bit full adder at one point and then built a small memory out of a bunch of electrolytic capacitors. I found that they would hold a charge for quite a while and that I could wire them across a latching relay to transfer the "bit" to the relay and simultaneously recharge the capacitor. I had a big stepping relay that I was going to use to control sequencing but I found that many of the relays he had given me didn't work and never got replacements for them. However, it did teach me a lot about the internal workings of computers at a fairly low level.
  • Cluso99Cluso99 Posts: 13,618
    edited April 29 Vote Up0Vote Down
    I still have a few stacks of listing. About to move shortly so a few more may go by the wayside :(
    Think I still have an unused box of my custom printed fan-fold paper.
    Oh the fun days of 17" fan-fold printouts ;)

    In the low 80's I started putting my code listing on microfiche.
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 21,852
    edited April 29 Vote Up0Vote Down
    One thing I should add is this: early on in my programming career I had a bad habit when things didn't go quite right. I would look at a block of malfunctioning code and think, "This should work." And I would comb through it coming up with all kinds of reasons that it must be correct. That, of course, was totally non-productive.

    Things got better, and I became more productive, once I learned to be brutal with myself. If it doesn't work, it can't be correct, so quit making excuses and look for the mistake!

    Also, regarding commenting, I typically comment the beginnings of spin methods, just to say what the parameters are and what it does with them. I comment every line of PASM code, because assembly isn't as easy to read as a higher-level language.

    -Phil
    “Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away. -Antoine de Saint-Exupery
  • potatoheadpotatohead Posts: 9,145
    edited April 29 Vote Up0Vote Down
    Edit: self taught here too. Frankly, started typing things into a Trs 80, then Apple 2, Atari and never stopped.

    Programming is a lot like writing. The more you do it, the better you can be, given you are willing to explore, take some risks, laugh at the laughable.

    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.

    I'll express a contrary view here and say there are two cases:

    Case one, work for hire, "official" in some way. In this case, "doing it right" means doing it in a way that conforms somehow. And again, this is like writing, formal writing of some kind. This is also true for something intended for others, or a shared effort. Communication is probably the best thing you can do. Doing this requires more. You have to make it work, and make it work in a way, or presented in a way that is also defined. This can be two problems, or something like a meta problem, instead of just the problem, whatever it is.

    Case two, and by far the more fun case and majority case for me, is I wrote it, whatever it is, for my reasons. I like to share, and I do, and it's freely given. In this case, I will write it the way I feel makes sense, and that is a balance of time, purpose and enjoyment. The right way might just be making something I wanted to happen, happen. Beyond that, there are few worries. Others can take it, rewrite it, improve on it, whatever. In this case, making it "better" or "right" may be more work and that may or may not be worth doing. It's your call, your time, your pleasure. Do what makes the best sense, and point back to "given freely" for those who may want more. You might not. We all have agency here. A lot of this is getting at the problem, avoiding meta problems. Make your stuff happen. That's why you started.

    On comments, I like narrative ones, not so much functional.

    X := input*5

    Commenting that in the functional way would be something like, "X is made equal to input from DAC multiplied by 5." Kind of useless really. People can see that.

    In the narrative way, the comment would be, "Scale DAC value to better match lookup table entries."

    Those are far more valuable, and require fewer updates to comments. Many of them will even work when a comment is old. The intent is there, and getting at intent is probably the hardest part in all of this. True for me. I will often look at code, and I'll comment it in this way first, to understand, then to use, modify, build on, learn from.

    One thing I often miss and want to do more of is to check limits, specify where it works, where it doesn't, and with what or how. Doing more of this will help you, and others who may encounter your code, to make better use of it. It also helps your thinking. Prior to writing something, thinking through those comments, or even just writing them out, can really help your focus. Each thing you write, function, procedure, whatever, gets a more clear, more useful, more understandable definition.

    If it's not needed, playing code golf isn't going to add value, unless it is somehow needed. Compute time, RAM, that sort of thing. Make it work, then make it work better, then make it work faster and or smaller. Refactor, rewrite, all apply here.

    If you aren't having some fun, you are doing it wrong, or need to get paid.

    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.
    Do not taunt Happy Fun Ball! @opengeekorg ---> Be Excellent To One Another SKYPE = acuity_doug
    Parallax colors simplified: http://forums.parallax.com/showthread.php?123709-Commented-Graphics_Demo.spin<br>
  • potatoheadpotatohead Posts: 9,145
    edited April 29 Vote Up0Vote Down
    Whit wrote: »
    By the way, it is very encouraging to me to see how many of you are self-taught.

    My first programs were written on an Apple ][ and a TRS 80 Pocket Computer.

    My most used program on the TRS 80 Pocket Computer added feet, inches, and fractions. My Dad and I - both architects - used it until calculators became available for that function. You can get one now for less than $15.

    Same!

    I still have a Pocket Computer. It's the fold out one, 2kb RAM, little 20 char LCD.

    For years I had a pile of sheet metal layout tools running on it. Computations of various kinds. Moved those into a CAD system, and then didn't need to do much else, so there you go.

    I also used it for statistical process control. I would input measured values over time, get back tolerance compliance data. This worked very well. I rarely had parts come back. Company adopted a lean scheme a few years later.

    Do not taunt Happy Fun Ball! @opengeekorg ---> Be Excellent To One Another SKYPE = acuity_doug
    Parallax colors simplified: http://forums.parallax.com/showthread.php?123709-Commented-Graphics_Demo.spin<br>
  • I have used TeamCity as a build-server for a while and really liked their duplicate finder.

    Like many programmer I like to copy and paste, say the existing Address-List-Window is quite similar to the new wanted Object-List-Window. So I copy the Address-List and start changing it into the new wanted List, removing and adding code.

    Later on the duplicate finder would show me the stuff both lists have in common and I am often able to refactor the code out into modules used by both lists.

    Modular programming is very helpful to allow reuse for other projects and shorter listings. I worked for companies that had the rule that no source modul was allowed to be longer as a printed page without explicit permission, I personally found this too restrictive.

    I really do like to read @JonnyMac's code, he is good at keeping code duplication out by using short sub-routines, has a consistent naming, shares a lot of useful code and is a cool guy on top of it. One can learn a lot of good coding style by just reading his sources.

    There are usually rules how to program provided by your employer, say if CamelCase should be used (or not), if variables should be prefixed with a type (or not), programming for a living since 30++ years I can easily adapt to the wanted style, same goes for the used languages and overall project structure.

    What is common is the importance of descriptive names for everything, I almost HATE programs where I find variables using I,J,X or other single char names, every professional editor I use has code-completion, so longer names take not longer to type, but increase the readability in any language.

    Very early in my life I programmed in COBOL, a very, very, very descriptive language with a lot of text to type and a quite restrictive overall source structure, but if done right one can read COBOL sources like plain English, not needing much comments.

    As @potatohead mentioned commenting what the source code does is USELESS, a programmer can read that right out of the source code itself, the comments need to show WHY things got done to archive WHAT.

    As @Phil said a short description on top of some code describing parameters, results and GOAL is most efficient.

    Enjoy!

    Mike
    I am just another Code Monkey.
    A determined coder can write COBOL programs in any language. -- Author unknown.
    Press any key to continue, any other key to quit

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this post are to be interpreted as described in RFC 2119.
  • msrobots wrote: »
    As @potatohead mentioned commenting what the source code does is USELESS, a programmer can read that right out of the source code itself, the comments need to show WHY things got done to archive WHAT.

    As @Phil said a short description on top of some code describing parameters, results and GOAL is most efficient.

    I just want to say I agree with this too. Useless comments just add fluff and make it harder to read (remember "word problems" in math class and having to sort through the fluff to find the real problem?).

    Also, the best thing I do to learn how to program is hold a code review. This is difficult, of course, because no one has time to ever read someone else's code. But I learn more from code reviews than anything else (preferably reviewing code I've written, but I certainly learn from reviewing others' code too). So, I'll put this offer out there: if you ever write some C/C++ code and want a review of it, let me know.
    And for anyone new to code reviews: be aware that getting a code review can be a very scary thing sometimes, and you NEED to have thick skin. You won't learn jack squat if someone comes in to look at your code and just says "yep, looks good!" So the best possible outcome is that they give you lots of (constructive) criticism - just don't get upset or distressed when that happens.
    David
    PropWare: C++ HAL (Hardware Abstraction Layer) for PropGCC; Robust build system using CMake; Integrated Simple Library, libpropeller, and libPropelleruino (Arduino port); Instructions for Eclipse and JetBrain's CLion; Example projects; Doxygen documentation
    CI Server: http://david.zemon.name:8111/?guest=1
  • I was pondering source commenting again the other day. You see I had just written this: https://github.com/ZiCog/sodor-spinal/blob/master/src/main/scala/sodor/sodor.scala

    Almost 900 lines of code with almost no comments. When I looked at it wondering how and where I might add useful comments I could not find any such place. So I did not.

    What that is is my attempt at creating a RISC V core for FPGA in a high level description language. My dilemma about commenting it is this:

    If one knows ones RISC V instruction set, and knows what this code is implementing (see picture here: https://forums.parallax.com/discussion/168355/sodor-spinal-a-risc-v-core-in-spinalhdl, and know ones Scala language and the SpinalHD library, then there is nothing to say comments. The variables used and their names are just taken from the block diagram, as are all the blocks in the code so there is nothing to say.

    On the other hand, if one is not familiar with RISC V and the given block diagram and Scala/Spinal then no amount of comments in the code is going to help!

    Perhaps some brave soul could take a quick look at that code and tell me if my conclusion re: comments makes any sense.

    I'm quite a supporter of commenting code. But often I have a downer on it because many times the comments are worse than useless, simply repeating what you are reading the code anyway or out of date or wrong or misleading.

    I always find one of the hardest part of programming is thinking up names for things. Drives me nuts sometimes.



  • It's a mixed bag. In your code, names help a lot. The brief comments make sense.

    My understanding of that code is not good enough to comment more fully than I am, which may be good for this discussion. But, what I did take a while to study began to make more sense.

    If I wanted to work with that code, and I do actually, but time..., I would get my references, and start mapping it all out. Once that was done, I would likely leave myself some notes. Build it, test it. Then continue from there.

    Frankly, the product of that exercise would be better as blog post where the sum of the reference material, my observations and some detail related to the code would make for a nice leg up for others who may have similar interests.

    I find I like comments more when there is a lot of math, or its assembly language where references to hardware, circuits all are necessary to understand things. Narrative style on those is a big win.

    Or, when it's a hack, or some unorthodox use and or abuse going on.

    On something like this, the intent is fairly clear, and likely more clear given more thought and review. This is descriptive language after all. :D

    Honestly, about the only comments I can think of would be a summary of the state of the project, limitations, plans, gaffes, etc...

    Theory of operation essentially. Maybe what it might be good for, and you may have those things somewhere too. I didn't look.



    Do not taunt Happy Fun Ball! @opengeekorg ---> Be Excellent To One Another SKYPE = acuity_doug
    Parallax colors simplified: http://forums.parallax.com/showthread.php?123709-Commented-Graphics_Demo.spin<br>
  • Heater. wrote: »
    ...I always find one of the hardest part of programming is thinking up names for things. Drives me nuts sometimes.

    yes, me too.

    Mike
    I am just another Code Monkey.
    A determined coder can write COBOL programs in any language. -- Author unknown.
    Press any key to continue, any other key to quit

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this post are to be interpreted as described in RFC 2119.
  • I really do like to read @JonnyMac's code, he is good at keeping code duplication out by using short sub-routines, has a consistent naming, shares a lot of useful code and is a cool guy on top of it. One can learn a lot of good coding style by just reading his sources.
    Thank you, that's a very kind comment.
    "When I write code, I do it so that in 6 months from now, some idiot has to be able to read the code and make sense of it. Usually, I'm that idiot."
    Yep. I could not agree more.

    Like many here, I am mostly self-taught. Still, I have had teachers and mentors. I think in all things we learn, it is good to look for a person that has the skill(s) we desire and ask them for guidance. I've been lucky through my career to have the opportunity to work with really bright people, and I have unabashedly asked for their guidance at every opportunity. Likewise, this forum is a constant source of programming nuggets to be mined, and I'm grateful that so many gifted programmers willingly share their tricks and techniques.

    Another lucky thing for me is that I get to do a lot of focused programming -- between EFX-TEK and Adventure Sports HQ (EFX-TEK partner), I am constantly writing code for the Propeller. This gives me the opportunity to learn from my own mistakes/experience. While working at Toro I was instilled with the belief that we should always strive to improve our products. By the time I release code to a client or the public (library, magazine code) it has undergone many changes. And those never stop. I will frequently see a comment in the forums that causes me to go back and reconsider something I've written in a different manner -- that just happened today.
    Jon McPhalen
    Hollywood, CA
    It's Jon or JonnyMac -- please do not call me Jonny.
  • potatohead,

    Thanks for taking a look.
    Honestly, about the only comments I can think of would be a summary of the state of the project, limitations, plans, gaffes, etc...

    Theory of operation essentially. Maybe what it might be good for, and you may have those things somewhere too. I didn't look.
    I think most of that is in the README file. As shown on the front page of the repository: https://github.com/ZiCog/sodor-spinal Including instructions on building and running it if you ever want to play.

    I should probably add the block diagram and other docs I'm working to, seems that is getting updated by the original Sodor project so the link I have there to it will soon be to a version out of sync with what I have done.


  • I'm a self taught coder as well. Started back in 1981. I have been working professionally as a coder in the game industry since 1993. For work, I mostly code in C++ (and we use some of the new modern C++ features (C++11 and C++14 mainly)), but I also program GPUs with HLSL shader language (DirectX 11, Shader Model 5). I also occasionally do some Python coding for work (it's integrated into our tools for scripting, among other things). My hobby coding is largely Spin/PASM.

    I can't really add much here, others have covered most things, but I will add my two cents to a couple things...

    Comments:
    For high level languages (anything not ASM) I generally write "self documenting code" with good variable names and function names. So comments are not super common, mostly just to explain the trickier bits.
    For ASM(PASM), I will typically comment every line, or small group of lines, because it's pretty much impossible to make ASM self documenting.
    Above all else, ALWAYS update your comments when you change code, never ever skip this, nothing is worse than a comment that is wrong.

    Naming:
    I'm with heater, the hard part is coming up with names for things. I tend towards longer descriptive names. It's the main reasons I made OpenSpin able to have 254 character symbols, for var names and method names in spin.

    Controversial Things:
    Tab should insert spaces, K&R style {}'s is wrong, 6502 over Z80, etc.

    However, above all else, be consistent. nothing worse than trying to read code that is inconsistent in it's style, naming conventions, etc.
  • davejamesdavejames Posts: 3,908
    edited April 29 Vote Up0Vote Down
    Whit wrote: »
    Any legitimate short-cuts, tips, or suggestions would be appreciated! Till then I will keep hacking away at it...

    Self-taught I am...and like others, I've taken formal classes and had the advantage of pretty solid mentors.

    One of those mentors made this suggestion:
    https://www.amazon.com/BASIC-Style-Programming-Proverbs-programming/dp/0810451158

    Regards,

    DJ
    Well-written documentation requires no explanation.
Sign In or Register to comment.