Allan Rasmussen's home page

• Use describing names (classes, methods, variables and other). Use a long name, if you can't come up with a short one.
• Have a consistent source code format
  • It doesn't matter if you use 2 or 4 spaces or a tab to indent, just always do it the same way.
  • Always indent! I will also recommend always to use the {} notation even if there's only one line of code, because the risk of errors when someone adds the next line of code is lower.
  • Only one statement per line
  • Don't use smart code.
       You might know how it works and what it does, but other people that are going to read or maintain the code might not.
       Don't use it just because you just learn about it or because you want to try it out. Do that in a prototype.
       Use it, if it is the right and only tool for the job.
       By smart code I mean things like:
    
    • Sealed classes (Keywords: sealed and permits. See JEP 409).
    • Record classes (This in includes Canonical / Compact Constructors) (Keyword: record. See Record classes).
    • Pattern Matching for instanceof (See Pattern Matching for instanceof).
    • Text Blocks (Operator: """. See Text Blocks).
    • Lambda expressions (Operator: ->. See Lambda expressions).
    • Double colon (Operator: ::. See Double colon (::) operator).
  • Don't spend a lot of time on other source code formating, because it doesn't really matter
• I write very few comments, because it is hard to write useful comments, but it very easy to write stupid ones.
  
  • Don't write the same thing as the code just in a different language
  • Write comments on the things that can't be fairly easy see from the code (or refactor the code to show it better)
  • Update your comments or delete them. Otherwise they will do more harm than good.
  • I write (big) comments when I do a hack
            (Making something work with very odd / unclear code or code that I don't understand why is working. Or fixing a bug in code that I can't change.)
• I write very few TODO's, because in my experience they won't get fixed any way. Fixed it now or ignore it.
• I use TODO's to indicate code that should (or could) be removed in the future, but maybe it can't be removed right now.
      Then I can easily removed it, if I years later make a new change to the code.

• Code for change: Design your code with the intent that it is going to be changed, but don't assume that you can guess in which direction
  • Design your application such that it can be (automatically) updated
  • Make sure that you can make changes to the database (Add, remove and change fields and tables) or other data storage like XML or ini files (I use a version number). If this requires a service window, then plan for it.
  • If you have some kind of configuration, then plan with some form of backward compatibility
• Make sure that top level exceptions and other errors are caught and handled (logged, viewed or both)
• Fail fast. Don't fail silent.
  • No home-made / fancy checked exception is required. A simple RuntimeException will do, and then let the general error handling report it.
  • A fully describing error message is also not required. A hint will do fine for now (Remember you have the stack trace and the source code), but consider adding important parameters / variables / other locale state to the message.
  • You don't have to check all parameters or other inputs. Just check those that will give an unclear error / message (now or later), or those that have taken time before to track down / fix.
• Try to minimize the number of 3^rd party frameworks dependencies. Many 3^rd party frameworks tends to:
  • Increase the knowledge required to maintain the code, and it increases the time it takes for new developers to learn how to maintain the code.
  • Increase build and deploy time, and increase the time and complexity of setting up the development environment.
  • Version clashes between common 3^rd party frameworks (Log4j I am looking at you), giving weird bugs that are hard to track down / requires hacks to get around.
  • Increase the amount of license issues / gray areas because it can be quite complex to figure out if it is allowed to use the 3^rd party framework or not.
• I don't write many unit tests
  • I have found that they takes very long time to write and maintain as the application changes, and I don't find many bugs using they. I find bugs faster using normal testing.
  • Other peoples unit tests tends to test stupid things that are not related to business logic, and they tend to write them in some fancy 3^rd party framework they just found on the Internet, and now everybody else on the project have to lean this framework to maintain them.
  • The unit tests tends to be switched off, when the project starts to have problems meeting a deadline, and they will never be switch on again, because it will be too much work. The unit tests have thereby been a waste of time.
  • I would recommend to use unit tests, if a bug reappears to avoid it from occurring again. I have not used this recommendation as often as I would have liked.
  • I use unit tests to tests complex algorithms that are easy to test (easy to test typically means that they don't depend on a lot of other things like a database for example)
            I typically do this via many calls to specially crafted but simple method in the following form:

    void test(inputParameter1 [, inputParameter2 ... ], expectedOutput)

            This method will simply call the method to test with the input parameter(s), and then check if the returned value is equal to the "expectedOutput" value. If it is not, the method will throw a RuntimeException. Simple and easy to understand and maintain for others, and it doesn't require any special framework knowledge.
            For an example of this see the combinator.test.ExpressionParserTest class in the Combinator project.

• Only data ones: Don't persist derived data (See Third normal form).
• Only programming code ones: Don't copy-and-paste code. Incapsulate it, generalize it, parameterize it and then reused it.
      If an API requires many / complex lines to be called, is odd or is missing a (obvious) feature, then make your own local API and reuse it. See the AR Common project to get an idea of what I mean.
• Only have user interface (GUI / TUI) ones: Don't have many ways to change the same thing. Wrap the GUI in components and reuse them.

• Don't nest if's (if possible)
• Don't nest many parentheses in the if condition. Keep the if's simple.
• Use return, break and/or continue to achieve it
• If you use an if-else-statement and one of the blocks of code is short (a few lines of code) and the other one is not, then have the short one first. This might require the if condition to be inverted.
• It is a variant of guard code

    private boolean groupsContainsANonNumber(String[] groups, boolean emptyStringIsNonNumber) {
        for (String group : groups) {
            if (group == null) {
                continue;
            }
            
            if (group.length() == 0) {
                if (emptyStringIsNonNumber) {
                    return true;
                }
                
                continue;
            } 
            if (!StringUtil.isStringADouble(group)) {
                return true;
            }
        }
        
        return false;
    }

    private boolean groupsContainsANonNumber(String[] groups, boolean emptyStringIsNonNumber) {
        for (String group : groups) {
            if (group != null && ((group.length() == 0 && emptyStringIsNonNumber) || (group.length() > 0 && !StringUtil.isStringADouble(group)))) {
                return true;
            }
        }
        
        return false;
    }

Source code details

• written by me (If not otherwise stated by comments in the code)
• in English. And as stated above: I don't spell very well in my native language and English isn't my native language, so the source code will contain spell mistakes.
• developed using the Eclipse IDE on Windows 98, Windows XP and the Linux distribution Ubuntu versions 8.4 (Old projects in old versions only), 10.4 (Old projects in old versions only), 16.4, 19.8 and 20.4
• tested on Windows 98 (Old projects in old versions only), Windows XP, Windows 10 and the Linux distribution Ubuntu versions 8.4 (Old projects in old versions only), 10.4 (Old projects in old versions only), 16.4, 19.8 and 20.4
• compiled and packaged (for download site) by the ABT project.
• indented with 4 spaces or 1 tab. Tab size is 4 spaces.
• in a mixture of Windows and Linux newline
• in UTF-8 encoding

Versioning strategy

Technology list

License