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

171–180 of 247 posts

Re: How to Build Good Software

#171

Post by mrfredward »

kitsune_ wrote: post #95
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.

I'm not disagreeing with the idea that there is variability in developer productivity. However, quantifying the most productive engineers by throwing around a specific random factor such as "10x" is rather idiotic. You have entire blog posts by Steve McConnell of Code Complete fame devoted to defending the 10x claim by citing 20 to 50 year old research that shows 5x to 20x differences across certain dimensions and th…

Perhaps "10X engineer" is just an easier thing to say than "5 to 20X engineer as described by this paper." Perfect numerical accuracy is not needed to make the point that there is a lot more variance in the productivity of engineers than there is with most jobs.

If someone suggests you focus on the 20% of customers who make 80% of your revenue, and you run the numbers and find a 75-25 distribution, should you call the person making the suggestion an idiot?

Re: How to Build Good Software

#172

Post by sethammons »

ValentineC wrote: post #128
solveit wrote: post #65

Earlier quoted context omitted.

I don't understand the point of replying like this. Clearly we agree that the Singaporean government is very good at getting things done, and we agree that the things it wants to get done are horrible. Why are you speaking as if our opinions differ? Why manufacture conflict where none exists? Is calling something a quasi-Orwellian dystopia now too subtle an expression of disapproval?

> Clearly we agree that the Singaporean government is very good at getting things done, and we agree that the things it wants to get done are horrible. Singaporean here. The government's mainly effective for tasks that are on a happy path. If your particular case falls through the cracks, it often takes phone calls, printing, postage, and weeks or months of waiting to get stuff done. (Personal experience trying to ge…

sounds like lots of govt. and corporate interaction in the US.

Re: How to Build Good Software

#173

Post by Silhouette »

ensiferum wrote: post #81

"2. Seek out problems and iterate;" This is bad advice. It's like saying "go into a bar and start picking up fights". If some part of the software has problems, runs slow or has bugs but nobody is complaining, then there's no problem. Why waste time improving it? Almost 100% of the time when you solve a problem you just create new problems of different kind in turn. Be lazy. The less code you write the better off you…

If some part of the software has problems, runs slow or has bugs but nobody is complaining, then there's no problem.

This depends very much on context. To pick an extreme example, if you're writing the control software for a nuclear weapon and you know you have a bug that might cause it to activate unintentionally if you eat a banana while it's raining outside, I think we can reasonably agree that this is still a problem even if so far you have always chosen an apple for lunch on wet days.

Re: How to Build Good Software

#174

Post by deathanatos »

dawidw wrote: post #90
goatinaboat wrote: post #71

Earlier quoted context omitted.

prefers working code over comprehensive documentation This is funny because “working code” might just mean that it doesn’t crash. But does it actually do what it’s supposed to do or does it reliably deliver the wrong results? How would you know without documentation? The software in the Therac didn’t crash, it quite reliably killed people with its “working code”.

Using that logic, what would be "working car"? When wheels don't fall apart? So I think "working code/application/program" is when it does what it is supposed to do. Including not crashing.

> So I think "working code/application/program" is when it does what it is supposed to do.

And the point of the comment you're replying to is to ask what is "what it is supposed to do". How do you know what the answer to that question is, without documentation or a specification? And if you try to rely on just verbal communication, in a group of people probably larger than about 1, they're going to have different ideas about what the software is supposed to do.

Some of the most challenging problems I've encountered have been looking at code that does something. What it does is clear enough from the code. But why it does it, or should it do that, that is much harder to answer, particularly if the person who wrote it has left the company or it's been >6 months and they just don't remember.

Re: How to Build Good Software

#175

Post by jeffmcmahan »

iEchoic wrote: post #159

> Reusing software lets you build good things quickly It also introduces unknown amounts of debt and increases the likelihood that you'll end up with intractable performance/quality/velocity problems that can only be solved by re-writing large portions of your codebase. This can be a dangerous cultural value when it's not presented with caution, which it isn't here. I think it's best to present it alongside Joel Spoe…

I agree completely. Dependencies solve problems but not for free - bugs, security issues, versioning headaches, performance problems, compatibility gotchas, churn, &c. I live by the following:

(1) If a problem can be exhaustively specified in a formally well-defined way (mathematical logic), it will be wise to adopt a mature implementation - if it exists.

(2) If a problem can't be so specified, all implementations will be incomplete and will contain trade-offs. I have to address these problems myself to ensure that limits and trade-offs suit as well as possible what the business needs. If I can.

So, (1) says I shouldn't parse my own JSON. (2) says I should avoid the vast majority of what shows up in other people's dependency trees.

Re: How to Build Good Software

#176

Post by Silhouette »

Excellent article, well grounded in the reality of software development. New developers and managers would benefit from understanding the practical points made here as early as possible.

I do think perhaps there is too much emphasis on reuse and particularly cloud services. Ironically, this is partly for the reasons given elsewhere in the article. If you rely on outsourcing important things, you also naturally outsource the deep understanding of those important things, which can leave you vulnerable to problems you didn't anticipate. Also, any integration is a source of technical debt, so dependencies on external resources can be more fragile than they appear, and if something you rely on changes or even disappears then that is a new kind of potentially very serious problem that you didn't have to deal with before. Obviously I'm not advocating building every last thing in-house in every case, but deciding when to build in-house and when to bring something in can be more difficult than the article here might suggest.

Re: How to Build Good Software

#177

Post by 0xffff2 »

ptero wrote: post #131
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…

> Documentation is essential. How things work is an important thing to document. I agree with this 100%. However, to be useful it needs to hit the right level of crudity. For most projects, a short ( It is best when this exists as a standalone document which is a required reading for any new developer. After this they can look at module descriptions, function docs, code, etc. and understand how to make sense of it an…

I think there's a lot of ambiguity in the phrase "generated from the code". When I hear it, I think if docs generated from doc-comments embedded in the code, which hare clean explanations written by a human. They just have the advantage of being right next to the code, so they're a lot more likely to be updated when the code changes than an entirely external document.

"Documentation" that is nothing more than the interface definitions in HTML for is worse than useless. I can get all of that from just reading the code.

Re: How to Build Good Software

#178

Post by whydoyoucare »

dkersten wrote: post #150
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…

Many years ago, I worked for a company where we were writing complex distributed telecom software and they had a wiki for documenting the system. I spent a few weeks meticulously documenting everything I did and anything that was touched by it (including defining all of the industry jargon and such). It was a great way to get a quick understanding of any part of the system, but I was the only person keeping it up to…

I believe it is equally important to determine the level of abstraction for the documentation, such that updating it is an infrequent task (essentially, every line of code change should not trigger a document change). It is easier said than done, but that's the best compromise I have arrived it.

At the very least, the document should capture high-level (again this is relative term) design, possibly an architecture diagram of major interacting functional units. The success measure should be the relative ability to build a mental model of the system by looking at this document for any newbie.

That design document would be a start, and most likely not "quickly outdated".

My personal beef with the agile camp is precisely this: when they let go of documentation, they don't do the design doc as well, and all that remains of the system is thousands of incoherent stories and huge amount of code.

Re: How to Build Good Software

#179

Post by chessturk »

arethuza wrote: post #151
spuz wrote: post #141

Earlier quoted context omitted.

But what if the definition of 55 changes? You'll be glad to have your table of constants then.

The project also defined HTTP, COLON, SLASH, WWW and DOT so that you would have: string url = HTTP + COLON + SLASH + SLASH + WWW + DOT ... I swear I'm not making this up....

Reminds me of http://pk.org/rutgers/notes/pikestyle.html

> "There is a famously bad comment style: ...

Don't laugh now, wait until you see it in real life."

Re: How to Build Good Software

#180

Post by 0xffff2 »

JohnBooty wrote: post #61
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…

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. My solution to this is old and fairly unpopular, but I stand by it: anything in the codebase that's not obvious to a new maintainer should have a brief, explanatory code comment. Generally, this falls into two categories…

>anything in the codebase that's not obvious to a new maintainer should have a brief, explanatory code comment

I'm not at all convinced that this is unpopular, but I think it's a whole lot harder than you're letting on. Unless you have a constant stream of new people coming in and you can convince them to give honest feedback, you don't actually know what's not obvious.

Post reply on HN