08 Feb 2020

Reinventing the wheel

History / Edit / PDF / EPUB / BIB / 2 min read (~351 words)

Why do we reinvent the wheel?

It is very common for developers to want to develop things themselves instead of reusing existing code. They prefer to know how it works so that if they need to make changes to the code, they know where to do it since they wrote it themselves. If they are lucky, they've been given a narrow set of initial requirements that could be fulfilled by a more complex/complete library, but they think that they can do it themselves or do it better. Thus they build themselves a square wheel.

One of the positive sides of developing something that already exists is that you can get a good understanding of what is required without having to consider all the other parts which may be required for other use cases. You're also free to explore the aspect of the problem that you find interesting or challenging.

One of the negative sides is that if you work on your own square wheel for a while, you never end up learning a library that might prove more useful. You also do not acquire the skill of learning new libraries and their strengths/weaknesses, as well as how you could help to improve them. Sometimes however by reading an existing library you will come to the conclusion that fixing said library is likely to take you more time than writing a new one.

In my experience, the main reason that has led me to write something from scratch even though I had access to code that partially did what I wanted was because:

  • the library wasn't able to sell me on the reasons I should use it instead of doing it myself, while I considered implementing the solution myself to be somewhat easy.
  • the code (organization, style) was so messy that fixing it would require more time than rewriting it after understanding the core concepts.
  • the library was not maintained anymore.
  • using the library would make my workflow slower.

06 Feb 2020

Great or acceptable software solution

History / Edit / PDF / EPUB / BIB / 2 min read (~285 words)

Is it better to spend a lot of time designing a great software solution or to implement an acceptable one?

In software development, the further you go down the development pipeline, the more expensive it is to change things. Once a solution is established and is being used by other parts of the code, replacing it becomes more expensive. Thus it would make sense to spend as much time as possible planning what you're going to develop before you develop it. Sometimes you however do not have enough information to make an informed design decision upfront and you actually need to implement something to explore and understand what will be needed to solve the problem. The exploratory implementation you do may end up being satisfactory enough that you do not see the need to redesign your solution.

When you implement a solution you generally have an idea of the use cases you need to support, but sometimes certain use cases are less common and require a lot more effort to support. As such, you have the choice between implementing a solution that would support both common and uncommon use cases but would require more time, or you could implement a solution that covers the common cases. Depending on the field you are in, you will have to choose between this tradeoff.

In the domains I've worked (game development, web development, machine learning), it has been more valuable to implement an acceptable solution that could be shown as providing value to the client vs designing a great solution until it was proven to be necessary.

Always make wise use of your time and assess whether quality or quantity is needed for your software project.

26 May 2019

Writing bug tickets

History / Edit / PDF / EPUB / BIB / 1 min read (~37 words)

  • Summary
  • Software version
  • Reproducible in latest version?
  • Environment details: compiler/interpreter, operating system, etc.
  • Steps to reproduce
  • Expected results
  • Actual results
  • Screen capture (if relevant)

25 May 2019

Web applications

History / Edit / PDF / EPUB / BIB / 1 min read (~61 words)

  • 3 different environments: development, staging, production
  • Write migrations for schema changes
  • Use ORM if possible over raw queries
  • Always make it possible for testers to report the version they tested against
    • Simplest is to have a meta field in the head section

  • Mockups
  • SRS
  • Database and software architecture
  • Implementation
  • Test/QA
  • Deployment

25 May 2019

Reviewing code

History / Edit / PDF / EPUB / BIB / 2 min read (~308 words)
  • Verify that the build/tests pass
  • Read the issue title and description
  • New code
    • Understand the feature and associated requirements that are supposed to be implemented
    • Verify code implements the desired feature and that the requirements are completed
  • New/Changed code
    • Check code contains tests
      • Is all the new code covered by those tests?
    • Verify the location of new/moved files
      • Are the files in the right directory?
      • Are they appropriately named?
    • Verify classes, methods, functions, parameters naming
      • Are they significant of their purpose?
      • Are they clear enough?
      • Are they respecting the naming convention?
    • Does the code respect SOLID?
    • Consider that when functions/methods signature change, code may now be backward incompatible.
      • Discuss whether this is necessary
      • Backward incompatible changes should be documented
    • In a weak typed or type hinted language, are parameters and return of functions/methods typed?
    • Are there TODOs that should be completed within this review?
    • Check code for code style issues
  • Bug fix
    • Verify that the fix is applied at the right location and will not "fix the symptoms, not the cause"

When reviewing

  • Provide specific and actionable feedback
  • Clearly mark nitpicks and optional comments
    • Alternatively, use an approach such as RFC2219 where you indicate whether a change is a MUST, SHOULD, or MAY
  • Assume competence
  • Provide rationale or context
  • Consider how comments may be interpreted
  • Don't criticize the person, criticize the code
  • Don't use harsh language