I'm compiling a collection of software engineering principles. The idea is to have them in a document with longer explanations and examples. Other than that, they're meant to be cited as justifications for this or that choice we make and left as comments in code or in conversations. Some are special cases or consequences of more generic principles. Here's what I have so far:
- simplicity
- least surprise
- separation of concerns
- design for the worst-case scenario
- explain the intentions behind any piece of code
- minimize future maintenance efforts
- minimize time to fix future problems
- no code duplication
- fail early
Note that this list is limited to "technical" principles in the sense that they're valid even for a team of one. There are more principles and guidelines for the interactions between team members but here I'm limiting myself to what could be or should be written down as part of a code base.
@mjambon It might help to see some Pro's and Con's of languages by @Crell about:
"Programming language tradeoffs."
https://www.garfieldtech.com/blog/language-tradeoffs
(same info from this post)
https://phpc.social/@Crell/112059376076977576
@mjambon My experience has been "no code duplication" can be overused by DRY folks to break into too many pieces. I've always argued about the 3rd time, the 1st time is good, the 2nd time is maybe, and the 3rd time is bad.
With the exception that if it's a true library in the system, then it should be used. But if you're just extracting the same value from an object the second time around, it probably doesn't need to be a utility function (yet...)
@koblas I think it's more about awareness... of when is a good time to stop duplicating the same thing over and over.
@koblas my current approach is to leave comments every time I write some questionable code so that others don't think it's the preferred style or that it should flip to another style if things were to change in a certain direction (e.g. one duplication within the same file is fine but 5 copies of the same string across the code base is not).
@mjambon Do you plan to share this document as a public thing for everyone, or is it only an internal project?