Most languages are capable of self documented source code, using comments and annotations. Some annotations can be parsed by a special program automatically and converted in HTML pages. Knowing how to create comments is an important skill developers must learn.
To achieve greater software quality, the source code must be built with some specific attributes. There are many other attributes for software quality. But here we are talking about source code quality. There is a difference. Top source code quality attributes are these three.
|1||comprehensive||readable, modular, consistent|
|2||maintainable||refactoring friendly, easy to debug|
|3||documented||use comments and annotations|
Here are some rules for a better design.
- Modular: A system is an aggregation of multiple sub-systems. The sub-systems collaborate and communicate using messages and rules.
- KISS (Keep it Simple Stupid): Just design the features that you need. Architectures that are more complex than necessary will result in sub-optimal systems.
- Holistic Thinking. A good system must define terminology and principles for definition of components and relations between them.
- Conceptual Brilliance. A system architecture may be elegant, but architects must not be blinded by the beauty of creation, and always review features with a pragmatic and detail-oriented eye.
We describe these rules that you can use in your future projects. These help you to have built-in quality. Some of these principles are using common sense and look obvious but some may surprise you even if you are experienced developer.
- If the code is difficult to read it is wrong;
- Split a complex problem into simple steps easy to grok;
- Do not stay astray from left side of the screen;
- Short lines of code are better than long lines;
- Module files and code sections must have a description;
- It is better to define global constants than to use magic literals;
- Group global constants in records or other composite structures;
- Local is better then the global. Create a local scope if possible;
- Favor explicit declarations against type inference or gradual types;
- Write subroutines only when you need them. Calls are expensive.
- Favor explicit loop and stacks over recursive functions or procedures;
- Avoid unnecessary data movement by using input/output references;
- Favor different names to overloaded subroutines and dispatch;
- Do not be afraid of long identifier names for subroutines and variables;
- Do not be afraid of large subroutines if your process is linear;
- Separate large sections of code using separators or comments;
- Do not be afraid do to refectory whenever you think is necessary;
- Do not create functionality that is not required or designed;
- Favor imperative programming over functional programming;
- Favor functional programming over declarative programming;
- Avoid deep class trees. They are hard to understand and debug;
- Avoid classes with features and favor mix-in classes instead;
- Favor precondition checking over exception handling;
- Favor efficient algorithms over parallel computing;
The name of identifiers in a language can support several characters. A name usually starts with lowercase letters (a..z) or capital letters (A..Z) followed by one or more characters or numbers. No special characters or spaces are permitted in the name except underscore (“_”).
A variable name can start or terminate with underscore or can contain underscores. The underscore is equivalent to space. So the identifiers that have space in a JSON or in a database can be mapped to internal variables that use an underscore instead of a space as identifier.
These are invalid identifiers
one+two 1'st step 1a, 31_, c-3
These are valid identifiers
this_is_good first_step a1,a2,a3 a, b, c, i, k, m, n, p, q, t
Variables usually have a meaning or a purpose therefore variable must have a proper name. Variables can’t use as names the language reserved keywords. Therefore we advise for variables to use a prefix all the time.
“v_” is a good prefix for variables; “p_” is a good prefix for parameters;
Using prefix is good but sometimes this is not good enough. When this is the case, you can give creative names to variables to make your code even more readable.
Example: In next example we name a logical variable and use the is operator. By not using any prefix for logical variable we make a very readable program.
constant URGENT=True :Logic; procedure main(situation:Logic) is begin if situation == URGENT then print("this is an emergency"); else print("this is a normal situation"); end if; end procedure;
This is Sage Code recommendation. You may setup your own rules. Just make sure all developers in your team follow the same rules. Otherwise some developers in your team will use one style while others will try to use something different.
Avoid it. This can be a disaster if your code is versioned as it should be. Automatic formatting is available for some languages and is a program that modify your source code to look nice. I strongly advice against it. You can be fired if you do not listen this advice.
Doing automating formatting for totally new code can be beneficial for learning how your code should look like. However do not apply automatic formatting and then add some other changes to the code and then check-in or push. It will make code review impossible.