The goal at the outset of any software project: write the perfect code. Design the code so it may be added to with ease and maintained painlessly. Implement the code quickly and without fault.
Unfortunately, designs inevitably fall short of flawless and bugs sneak into code. Software projects should be built as perfectly as possible, certainly. However, if a team ignores the reality that the code WILL NOT be perfect, it can be doomed to spend all of its time trying to fix an unmaintainable mess. There are options for teams seeking to minimize the impact of inevitable project problems.
Sometimes programmers don't make code that is well designed. Sometimes programmers don't even make code that works. What programmers CAN always do, however, is make code that is clear and understandable.
If an existing function is broken and will stay that way, add "broken" to the name. Don't pretend poorly designed functions are simple by giving them simple names; make the complexity apparent in the name. If the purpose of a variable is nuanced, spend the extra characters to make it obvious (don't worry, your computer has enough space).
While investigating a bug, a programmer finds a function that is difficult to understand. After stepping through the logic, the programmer determines that the function is indeed broken. However, the programmer does not have time to fix it now and will have to come back to it later. While the bug may be able to wait, the lack of clarity should not wait. At best, the programmer should refactor the function with better naming so it is clear, even to another developer. If there isn't time for a refactor then the programmer can at least leave a comment explaining the function and purpose of the function. Even though the function is not perfect, or even working, it is now clear enough to save future developers the effort of having to investigate the issue again.
Well-designed code should be SOLID, the 'S' of which means 'Single Purpose'. In reality, code may be written that has multiple purposes. If a function says is called 'update_user_preferences' but in reality it also updates an audit log as well, then a better name would be 'update_user_preferences_and_update_audit_log'. This clearer name will allow future developers to accurately understand what the function is doing without first conducting a time-consuming investigation.
Image a function that accepts a time, an origin time zone, and a target time zone. The function will return the time in the target time zone based on the given time in the origin time zone.
This function will have two 'time' variables: one in the origin time zone, and one in the target time zone. Calling these both 'time' would be time simplest approach. Another simple approach would be time call them 'time_1' and 'time_2'. However, clearer names would be 'time_in_origin_time_zone' and 'time_in_target_time_zone'. Notice that the variable naming reflects the phrases used in the prior paragraph to describe the purpose of the function. Though the names are much longer, they make the flow of the function clearer for the next developer to read the code.
