Ask HN: Good Software Engineering Guidelines to Implement in Company | Hacker News Reader

Ask HN: Good Software Engineering Guidelines to Implement in Company

3 pointsitsjustaway2 comments

If you know of good publicly available software engineering guidelines that cover the following areas:

  - What abstractions to use and why, how to design them
  - Common patterns and solutions, what to use and what to avoid
  - What test at what level and why
  - How to structure code in files/libraries/packages
  - How to contribute and review changes
  - How to document code
  - ...

Please suggest it in comments. It would be great if decisions are justified, like: "Here are N foundational principles and here are how they implemented on each level".

A bit about a problem I want to solve: From a team of 5-7 people we grew to several distributed teams and have newcomers from various backgrounds (c#, python, go, while we mainly write in typescript). What I see more and more is that each team or even each employee solves problems differently, using different abstractions etc. (and it is easy to do because we have microservice-ish architecture) - because there is no more shared approach. Frequently, when I contribute to other people code I have to spend time just to understand what's happening, how code is laid out and why (too often it is just personal preference). I imagine other employees have the same problems too, and it affects overall effectiveness - a lot of time wasted on unnecessary cognitive load.

It seems like engineering guidelines, if composed carefully, would help solve at least some of these problems.

> It seems like engineering guidelines, if composed carefully, would help solve at least some of these problems.

That's now how this works. It's hard to know how to design programs, it comes from experience, you are paying your engineers to apply that expertise. There isn't a formula for all problems.

Every large software company I have worked at simply accepts this, and allows engineers to do solve the problem the way they want, while requiring interfaces between teams/software to work properly.

Besides that, there are a few approaches you can take to share knowledge: 1. Limit the number of technologies used in your stack. You just listed 4 languages that all fill a similar role. If that was 1 that would reduce a lot of the cognitive load. 2. Cross pollinate engineers so that they get to work on all parts of the code.

I have to spend time just to understand what's happening, how code is laid out and why (too often it is just personal preference). I imagine other employees have the same problems too, and it affects overall effectiveness - a lot of time wasted on unnecessary cognitive load.

All of that is necessary cognitive load.

It's hard, and that's why you get paid.

Maybe not enough, but that's a different matter.

Anyway, there needs to be a business case for creating, distributing and enforcing guidelines. Usually there isn't and your question doesn't make one.

Beyond that there needs to be an established workplace culture where people take engineering guidelines seriously, production staff follow them, and compliance is a way in which leadership measures individual contributor performance.

If there isn't organizational buy-in, guidelines are pretend work. They look like work and are easier than the actual work.

Just doing the hard work is the simplest thing that might work.

Good luck.

Reply on news.ycombinator.com