Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to Build Good Software

csc.gov.sg

Post reply on HN
Print view View original

111–120 of 247 posts

Re: How to Build Good Software

#111

Post by konstmonst »

clumsysmurf wrote: post #60
PaulRobinson wrote: post #50

Earlier quoted context omitted.

"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as s…

Thanks for the thoughtful response, this is helpful. > Ideally it should be in version control and be generated from the code .. May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this? Thanks.

Use graphviz (dot tool for example) for state machines. It is a text format where you list state machine transitions and it generates a visual representation.

Or better yet: generate your state machines from same format you would use to generate visual representation.

Re: How to Build Good Software

#112

Post by PaulRobinson »

clumsysmurf wrote: post #60
PaulRobinson wrote: post #50

Earlier quoted context omitted.

"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as s…

Thanks for the thoughtful response, this is helpful. > Ideally it should be in version control and be generated from the code .. May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this? Thanks.

Don't be afraid of building a product specification, and doing it in Markdown and auto-generating a mini-website out of it.

Just build a product specification for how the product works (which is useful documentation), not how the product will work (which is waterfall).

We're experimenting with this a little, and I'm getting into document-driven development a little: if the product spec is in markdown, why not create a pull request on it as part of your story/project planning that shows the changes that would happen as a consequence of your work. Once the story is done, you can merge the pull request, even. We're not quite there with this yet, but I'm optimistic.

Putting design assets into your repo is also acceptable, and also paying time and attention to commit messages can be really, really helpful. I love this talk, for example: https://brightonruby.com/2018/a-branch-in-time-tekin-suleyma...

Re: How to Build Good Software

#113

Post by ikll »

Ma8ee wrote: post #87
dajonker wrote: post #76

Earlier quoted context omitted.

I disagree with that, if you describe it as stated in the article: "Overall, good engineers are so much more effective not because they produce a lot more code, but because the decisions they make save you from work you did not know could be avoided." I've seen plenty of poor decisions that cause 10x the work, and end up with something 10x less maintainable.

Anyone know how to demonstrate this to management? I’m quite certain that my boss think I’m a crappy developer, because I usually take longer than other to produce the same amount of code. But I’ve reduce the amount of code we need to write with three quarters, but that is harder to demonstrate.

Reducing the amount of code shouldn't be the end goal, but a way of increasing quality.

You should seek to demonstrate instead that you're making software that is more malleable, has less bugs, is easier for new hires to understand, is easy to add new features, etc.

Re: How to Build Good Software

#114

Post by hising »

mr_tristan wrote: post #17

This struck a chord with me: "Software Is about Developing Knowledge More than Writing Code" I've experienced more issues caused by management passing around tasks between teams and never paying attention to knowledge and knowledge transfer. What's amazing, is that in over 18 years as a software engineer, I've seen this so many times. Teams will function well, then the institution tries to change. Often they will try…

> "Then you have tons of teams, and communication becomes very challenging"

communicationChannels = nrOfTeams(nrOfTeams-1)/2

More people should read The Mythical Man-month

Re: How to Build Good Software

#115

Post by axilmar »

The initial proposition of the article, that software is bad because it follows the lifecycle "gather requirements - write software - deliver it" is simply wrong. There are huge projects in specialized domains that are delivered on time and on budget and use this approach.

The problem is lack of knowledge. The successful projects mentioned above did not have a lack of knowledge, and so they were finished successfully.

When there is a lack of knowledge, then it makes sense to use the iterative approach...as knowledge is slowly gathered, the software gets improved. As with all things in life!

Re: How to Build Good Software

#116

Post by abdullahkhalids »

PaulRobinson wrote: post #50
clumsysmurf wrote: post #42

Earlier quoted context omitted.

> "Software Is about Developing Knowledge More than Writing Code" The company I work for uses Scrum. They consider the User Stories + the code to be everything you need. I struggle with this, but my manager says they don't want to get tied up doing documentation "because it goes out of date". Beside, they are being Agile which "prefers working code over comprehensive documentation". I am wondering what other companie…

"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as s…

> Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date

Interestingly, this has been a big point of discussion in the Dota 2 playerbase. Dota 2 is one of the most complex games ever created and it rapidly changes on the order of days or weeks. At one point, the in-game descriptions of spells were months or years out of date because they were being updated manually. After much hue and cry from the community, the developers finally made the tooltips get generated from the same code that determined the spells' effects. Things are a bit better now.

There is still a quite a bit of ways to go though, in terms of generating documentation for all the other mechanics in the game, which are crucial for gaining competency in the game, but which are only available due to third-party community efforts (often via people reading the game's codebase to understand subtleties), instead of being available inside the game.

Re: How to Build Good Software

#117

Post by andy_ppp »

I've personally been thinking about this for some time and wondering if in the real world this looks like building as much as possible at the database level and treating your DB as a state machine for your app, aiming to disallow whole classes of errors and communicating the design of the business logic at the SQL functions/triggers/data layer, separate from the API, Services, Programming Language, and Frontend layer(s).

This means that instead of lots of issues with business logic being separate from the data the business logic and data sit together and prevent your system from getting into bad states.

Thinking about this, maybe I just stole this thought from Derek Sivers: https://sivers.org/pg

Re: How to Build Good Software

#118

Post by fbr »

axilmar wrote: post #115

The initial proposition of the article, that software is bad because it follows the lifecycle "gather requirements - write software - deliver it" is simply wrong. There are huge projects in specialized domains that are delivered on time and on budget and use this approach. The problem is lack of knowledge. The successful projects mentioned above did not have a lack of knowledge, and so they were finished successfully…

Yes, the lack of knowledge is definitively one of the issue.

But starting a "gather requirements - write software - deliver it" lifecycle because you are confident that you have all the knowledge is one as well.

Re: How to Build Good Software

#119

Post by lelima »

siempreb wrote: post #102

> 3. Hire the best engineers you can. This is where most companies fail. Yes, they do want the best developers, but for the budget of an average junior/medior dev. For some reason most companies/managers I worked for do not understand the financial impact of a not so good developer. Or the other way around; they fail to value the best developers and are unable recognize them. I've worked for plenty companies where th…

>"3. Hire the best engineers you can."

If every single company wants that, where is he space to grow and learn from mistakes?

Maybe I'm wrong but I think those "mediocre dev's" learned a lot building a big app from scratch, solving bugs and refactoring.

Re: How to Build Good Software

#120

Post by loup-vaillant »

exhaze wrote: post #94
barrkel wrote: post #82

Earlier quoted context omitted.

The "but" negates any disapproving effect it may have had, because structurally the latter part acts as a justification for tolerance. "The tool is squeaky but it gets the job done" - you wouldn't expect the speaker to do anything about the squeaks. Squeaking is tolerable. "The tool does the job but it's squeaky" - you would expect the speaker to do something about the squeaks. Doing the job isn't good enough. Your c…

Comments like this are part of the reason why people like Sam Altman stopped posting here. Can you just give the poster the benefit of the doubt that they just admire the efficiency of the Singaporean government, not that they're endorsing authoritarianism as long as it's effective?

Never acknowledge any quality of the Enemy. The Enemy is Bad, therefore it is also weak, stupid, lazy, cowardly… Because the risk of being perceived as praising the Enemy always trumps the consequences of underestimating it.

Not the best example of crowd wisdom.

Post reply on HN