If you already have a handful of different technologies in the project, it is hard to maintain a good level of knowledge for them. Adding another language or framework will not help. It most of the code is stable, so that it never change, and simple enough to be replaced easily when an upgrade is necessary, this is less of an issue. But if you have a lot of code that is still actively maintained by the team, pick something that is already existing in the ecosystem. If the technical requirements are new, say you will build the first native smartphone app for the project, exceptions must be made. If you are afraid that the technology you have won’t be fast enough, write a small test. Guess at the part that will demand the most of the system, implement it for a load test in a technology you already have. Then you will know if you need to introduce more complexity to the project or not.
If you do not have a lot of code in place, but you have the people, let them decide. Not from the shiny toys they want to try, but something they have experience in. Set aside time to experiment on new technology outside of the main project to play with the shiny stuff. That is not for production. If you need to introduce new technology, as in the smartphone example above, make sure that the entire team learns enough to at least be able to fix a simple bug and deploy to production.
Languages and frameworks have communities. One of my favourite podcasts, >Code, have panelists who learned Ruby because of the people who go to Ruby conferences. If you need to introduce something new, try to get a feel of the people who already use the technology. Read the code of conduct for the major conferences. Look at the tone in replies to bug reports and feature requests.
It you do not have a team, or the team needs to grow, can you hire for the technology? Senior developers should, in my opinion, be able to learn any technology quite quickly. But it might be easier to choose something that people already know and use. I would say that this is extra important if you are not the owner of the product, but helping a customer to get it started.
Beside the “people culture” around a technology, there is also a programming culture. Look at the testing frameworks and what patterns people use. Will it be easy to find high quality examples online? Is the standard way of doing things containing patterns that will prevent you from following good practise? An example was a framework that encouraged scripts that swapped lines in configuration files, instead of allowing different configurations when building your target. That practise then also leaked into other parts of our project, wreaking havoc in the setup of originally more sensible frameworks. People will learn from what they do, don’t bring technology with bad practises into your ecosystem. Overly powerful testing tools is also a smell. If you need to “power mock” something, that is a sign of bad design. If all the focus is on integrated tests, that is also a warning.
Yes, if you do not have very specific requirements, that you have verified are true, the actual language comes last. For projects that are totally new, where you know you have enough people, and multiple languages are good candidates, you might need to consider the language design. In that case my preference is to look for two things: integrity and decoupling. How easy is it to make sure that my assumptions of the state of the running program is correct? This contains things as dealing with null, memory, types and exceptions. How easy is it to write modular code? That has to do with things as interfaces or protocols, the status of functions, imports and the Liskov substitution principle. What I value in a language change as I learn more.
Writing code for people (including yourself) is harder than writing it for the computer. That is why the people aspect of a technology is more important to me than the technical aspects. That is true also when choosing a language or a framework.
]]>The best code is the one we never write. Perhaps user research shows that there will be no value. Or there might be a library we could use, or some service.
If we have to write code it should have an interface so clear that it tells all there is to know. If the code can be trusted, and we know how to use it, there is no need to read it.
If we need to read it, at least it should have so little responsibility that there is only one reason to change it. And if there is only one reason to change it, nothing else should be at risk breaking due to that change.
If we have to change it, like really change it, keeping some functionality and changing other parts. Then it should at least tell us so much about it self that we know what is going on.
This is my code type top-list. What is your favourite kind of code?
]]>It is not always the case that we immediately spot the reason for an error in a codebase. Sometimes it is hard to find due to the design. In other cases the definition of correct behaviour is the problem. It might also be a lack in understanding when it comes to the technology used. This checklist is useful regardless of your knowledge of the language you are debugging. Depending on domain knowledge, technical knowledge and the state of the code base, how long the steps take and what information they give, will vary. This is, as most knowledge work, best done together with someone else, or with an entire team.
Write a test, of some kind, that captures the unintended behaviour. In worst case it is a description of steps to take written on a piece of paper. Best case is a unit test. This will define where we see the problem, with its setup and the state it leaves the program in.
Do we know for sure that this is a problem, not just a state where the behaviour is not clearly defined? Make sure that we know what the code is supposed to do in this particular case.
Are we sure that this is where the problem is caused? Check that the in-data is correct, and that the data out is not as expected. Try to narrow it down, define as little code as possible where the error might be.
Has it ever worked? If it has, what has changed since then? Version control is your friend here.
Is the IDE saying anything? A real development environment uses parts of the same algorithms as the compiler/transpiler/interpreter, to be able to give hints and syntax highlighting. There is also often static code analysis tools that can highlight practises that make the code fragile. Use tools.
Are there inputs, not stated as such, in the code we are looking at? Some code use state that is external in some way. One way to check this is by trying to write a unit test, instead of an integration test. What do we need in our setup to make it work? The state could be a global variable used by a collaborator, today’s date, or some settings in the system. Make sure that we know all the actual input data to the code we are investigating. Try to make the implicit input explicit when testing the code.
If there is comparing going on, is it done correctly (for that language)?
Do we know what could be null/nil/empty? Keeping null-checks at the boundaries of code makes this easier. Use the tools the language provide to deal with missing data.
Are data-structures used as intended? If iteration happens, are the boundaries the right one? Do the data-structures have any quirks in this framework?
Are there other language features that could be a problem? In Python, default arguments can turn into singletons. In ObjectiveC a method call on a deallocated object will return 0, or nil, but succeed. Try to rewrite the code, even if it turns it bulkier, just to see if misdirected “cleverness” might be the problem. Then read the documentation to understand what happens if the behaviour changes.
Is the flow of execution as we think it is? Use a debugger to step through the calls, following the control flow. Test cases can also be run in debug-mode. Make sure that there are no code skipped. One example is if code is executed as part of a condition, that is already evaluated as true, and therefore skipped.
Are we working with asynchronous code? If we are, then make sure that it is done correctly. Test ways to make sure that all of the suspect code is run synchronous, to eliminate logic errors that are not timing related , even if the code can never run like that in production.
Is everything what we think it is? Is the runtime scope clear? Do we have inheritance, this/self references, variables or functions that might shadow each other, or other things that might not be what we assume that they are? Do we reuse variable names or references? Might there be things where ownership is unclear and it is garbage collected? Use a debugger, or print statements, to check that things are what we expect. (Playing Destiny’s Child while doing this is optional, but it is a good reminder that scope in JavaScript is tricky.)
Take a break, if you have not already. At this point I might start searching the internet, or try writing a question at Stack Overflow. (Often the solution is in writing the post, not posting it.) I might also call a friend. My experience is that the harder the answer is to find, on the internet, the more likely it is that the mistake made is really basic.
Hope this list helps. I will use it the next time I get stuck on code not working as I intended.
How do you find your mistakes? Do you have anything to add? Have I missed anything language specific that is not included in the steps above?
]]>Split up the thing you are testing. Create a collaborator and test that separately or just split up the function. Splitting up view logic and rendering is nice and make testing easier.
Cheat codes: “separation of concerns”, “model view controller”, “view model - model view”
Sometimes the test depends on a system state or some other thing that is hard to control in the test. Inject the tricky thing as a dependency (fancy word for parameter) to the function/method. Today’s date should always be injected as a dependency if used.
Cheat codes: “dependency injection”
Wrap the framework in your own code and create a double for the wrapper. That will also isolate the framework, make it easier to adapt, replace and upgrade.
Cheat code: “ports and adapters”, “Hexagonal design”
Try to avoid side effects in your code as far as possible. Isolate necessary side effects (as sending/getting data) to specific areas of the code — the shell. A function or method that does not return anything, aka a void function, is a sign of a side effect in action. Make sure void functions do not contain any conditionals (if etc.). Write the rest of the code without side effects, levering data. If that is the only place containing logic, it is the part most important to test. And that can be done without tricky things as mocks.
Cheat code: “pure functions”, “io monads”, “functional core - imperative shell”
Sources:
]]>