Coding Style & Tips

The Ron Spain Programming Style Guide & Tips

My style often tells you to do the opposite of what many are taught. For example, I tell you to avoid comments and whitespace where possible. Find out why below.

Shorter First

It's best to put the shorter or simpler items first. For example, int x,startTime; instead of int startTime,x; requires less eyeball movement and hunting to find either variable declaration.

Similar Together

Keep similar or related lines of code together where possible, making code easier to both read and check for mistakes.

So don't write the following C code:

++x;
printf("%d\n",x);
++y;
printf("%d\n",y);

You should write it like this:

++x;
++y;
printf("%d\n",x);
printf("%d\n",y);

It works the same either way, but it looks better the second way, and it's easier to spot any typo.

Avoid Comments

Avoid using comments where possible, i.e., only permit comments when needed. Remove excessive comments from any copied code. To avoid using comments, use descriptive function names and macros. Why would I tell you to avoid using comments and even actively remove them when they are only there to help? Because excessive comments can make even the simplest of code seem huge and complicated, and comments are often wrong. Comments are an unreliable alternative to looking at the code and seeing what it does. Only if for some reason it is damn-near impossible to figure out should you use a brief comment.

Using ASCII art in comments is not helpful. We don't need every comment inside a rectangle made of asterisks, bless your soul.

Comments are most helpful when learning as a beginner, working as a team, releasing open source code, or when you come back to your own code after weeks or months and you won't remember everything you did and why, but it's best to avoid overuse of comments.

When you're just fooling around, you probably shouldn't be wasting your time with comments, and most of what you code should be fooling around, especially at first. That's how you learn.

Avoid Excess Whitespace

I indent with one space. Tab seems inconvenient for me for general use. I don't mind if someone uses two spaces per indentation level to make it easier for some to see. Four seems excessive to me, but if you for whatever reason can't see spaces properly, feel free to use as many as you need. Maybe you could use 20 spaces per indentation level.

With less whitespace and comments, you get to see more code on your screen at once, and the code is the important stuff here.

I try to avoid leaving stray spaces at the ends of lines or including lines that contain only a bunch of spaces, because these just make source code larger for no reason. Many coders seem oblivious to these. Some could say it's a waste of time when we have hundreds of gigabytes of space on modern drives, but I disagree. It doesn't require any great commitment of time to keep one's code clean of junk characters, and it makes it easier and slightly faster to distribute over the internet to thousands of users. And it looks more professional and conscientious to those of us who have our text editors set to show trailing blanks. It's part of a "tiny is good" philosophy to avoid being wasteful.

Short Names

Use short variable names where possible. Call the string s, the iterator i, the coordinates x and y, the number n, the counter c, the function f, the return value r, etc. Use a and b instead of longname1 and longname2. Only use a longer name if the purpose of a variable isn't clear. But long names can be useful sometimes as descriptive names for args of functions.

Fun fact: When I started programming as a kid, I used z as the interator for almost every loop because it was more convenient than i, which was not an easy key for the untrained finger to find on the keyboard, especially when coding in the dark. It creates some problems when you use also z for the third dimension in the same program. I also used z$ for keyboard input. Z made some handy variables.

Generic First

Put generic or reusable functions first, before functions that are specific to this program.

Simple Functions

Break down tasks into simple functions. If a function becomes long or its innards become more than a little indented due to nested loops or if...then blocks, it's usually time to try to break it down into simpler functions. Simple functions with good names also help to reduce the need for comments. You can build high-level functions from low-level functions, and they're easier to understand that way.

Don't Duplicate Code

If you have any length of code or mathematical operations that are repeated anywhere in your program, you should generally code that into a new function and call the function where needed instead of using duplicated code. This makes it easier to maintain, debug, inspect, etc. Only in parts of a program where speed is critical would I duplicate code. In C, functions can be inlined so there is no overhead.

One Job Per Line

Don't try to do everything in one line. That way of coding is likely to be harder to debug or maintain. Perform only one or two tasks per line of code.

Programming Tips

Don't make too many changes to a program without testing.

Test every function that you write. When a function is buried in a large or complicated program, it can be hard to see if it's working as expected.

Use print statements during testing and debugging to see what's really happening. When all you're working with is assumptions, there is much potential for mistakes.

Learn how to debug your programs. Try not to give up when there's a difficult bug. Learning to debug is part of learning to program, because there will always be bugs. No one can write bug-free code except very small programs, so get accustomed to solving the puzzles of the bugs. I'm not saying you ever need to use a debugger.

Don't delete code. When you change a section of code, don't remove the old code. Just comment it out, so if there's a problem, you can use the old code to compare with the new code to help find the problem or just reinstate the old code. Only delete old commented-out code when you're sure it's no longer any good.

If you're rewriting a function, instead of removing the old function, keep it there in commented form until you're sure the new function works perfectly.

Increase the font size in your editor. If you can't tell a colon from a semicolon, the font is too small. Some of you can't tell your colon from a hole in the ground.

First, make it do something; make it perfect later. Get your program to do something first, and worry about the details later, after the basics are working. Don't keep coding and coding without having something to test and admire and think about. The more you code without testing, the more bugs may accumulate. Solving one bug can be hard enough. Solving hundreds of bugs might be harder than starting over, so don't keep coding without testing. If your idea requires a ton of coding, try to create a simplified prototype of your grand idea first.

Code whatever you're thinking about right now. There's no need to force yourself to type the lines of code in any particular order. Modern text editors allow you to move the cursor instantly to insert code anywhere. It's easier to do that than to force yourself to keep mentally switching tasks.

If I'm writing a function, I might start with the return statement, which comes at the end, because I know it needs to return a certain type of data. And now I know I need variables for the return value and other things, so I write the beginning of the function, where variables are defined. By now, I have a good idea of how the function needs to work, so I write the middle part. I just wrote whatever part I was thinking of at the time. Work with your brain instead of fighting it. Code whatever you're most prepared mentally to code right now.

When learning, have fun. You should make a lot of fun little programs, even if some of your early work might seem silly to some. It's supposed to be silly when you're starting out. Also code a lot of simple utility software. I wouldn't start with big projects. You should have big dreams, and work towards them, but you don't try to fly across the Atlantic as soon as you learn to fly a plane, much less while you're still learning. A beginner can probably code a big project, though, if persistent and using my other advice such as starting with a simple prototype.

Find a book or tutorial that is good at teaching you. If you don't understand something after carefully going through the tutorial a time or two, just find another tutorial for that part. Don't give up or skip useful information just because the tutorial you're using is lacking or unclear in one part. There are dozens of tutorials and examples out there for almost everything, so just find another one if you don't get it. Someone out there can explain it properly.

Tutorials can be good, but sometimes what you need is just example code. Skip the overly wordy pages of those who are trying to create content by continually stating the obvious or burying the useful information among endless paragraphs of incoherent babbling.

Don't be afraid to edit some code and see what happens. That's part of the playing and learning process. If you're afraid to edit code, you won't learn to code. If you have an idea or thought, feel free to try it and test it and see what happens. You can and should carefully back up the original version of the code. If something goes wrong, you can just go back to the old version. Maybe the program crashes, but unless you're doing something very wrong, there is no permanent harm.

When testing some PHP code, I run a local server so I don't stress the resources of the web host in case my code has a bug.




Page generated in 0.004602 seconds.

© 2024 RockyMount.US