Standards and Conventions - RobertArtigas/RobertArtigas Wiki

Original URL: https://github.com/RobertArtigas/RobertArtigas/wiki/Standards-and-Conventions

Standards and Conventions

These are the things that you consistently do to in your program that when other programmers look at your code makes it easier to understand your code structure, placement, and logic. Making things easier for the next programmer to understand what you did is a best practice type of thing. That best practice encompasses a lot of things, and it is sort of like quality, you know it when you see it.

Programming is an individual and collaborative endeavor. A balance should to be reached. Get it working (solve the problem), test the solution outside of production (you prove that it is working), clean up the code (refactor), and leave a trail of bread crumbs (documentation and comments) for the next programmer to follow. Who knows who will be looking at the code six months from now. It might even be you.

Write these standards down somewhere. Make sure all programmers know where they are located. Make sure the standards are followed. Over time, these standards will save a lot of programmer effort in maintenance and training.

Development vs Maintenance

There is no development coding vs maintenance coding. The moment you write a line of code down, it becomes a line of maintenance code. If you got the least experienced, the newest folks, fixing bugs right off the hiring line, without some form of mentorship, training, paired development, and code review, it will be the most costly code that your enterprise will ever repair.

Please ponder what your choices are: Is the least experienced person on the company business practices, the person you want fixing the production code that handles your customers?

Performance vs Clean Code

Do not choose between the two opposite approaches while excluding the middle. 1) Make it work, 2) make it beautiful (IE, readable, testable & maintainable), 3) measure if and where exactly it actually goes too slow, and 4) optimize only those parts for speed, even if it has an impact on the beauty you got in step 2.

In most modern programming (embedded, game programming, and such other areas being exceptions), there is no need for premature optimizations. You only need to speed up the things that are measurably too slow.

The code tells me: Who are you?

If you write code long enough, it does not matter what computer language you write in, your code will show me who you are, what you have learned, and how you have applied what you have learned.

Your code develops a style and eventually can be recognized as your code, even if your name is not anywhere near it. Think about that specific side effect when you are writing anything.

The statements "the code works" and "it does what was asked for", while they cannot be argued against, has been used as an explanation for a "minimum" level of effort and quality. And while we are all occasionally guilty under pressure for doing this, it should not be our default "standard" of quality.

Good code is clear and understandable. Good code can also be maintained by the next person that gets the responsibility for that code. Ultimately, you are not coding for yourself, you are coding for others. Your maintainers, users, and stakeholders.

How do I use the truest, highest expression of myself in service to the world?

Wiki Main Repositories