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

61–70 of 247 posts

Re: How to Build Good Software

#61

Post by JohnBooty »

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…

    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.

1. Hacks/kludges to get around bugs in hardware, external services, or included libraries. These manifest in code as incomprehensible, ugly bits of code that are difficult to distinguish from code that is simply "sloppy" or uninformed. More importantly, they represent hard-won knowledge. It often takes many programmer-hours to discover that knowledge, and therefore many dollars. Why throw it away? (Tip: include the version of the dependency in the comment, ie)

    # work around bug in libfoo 2.3, see blahblahblah.com/issues/libfoo/48987 for info
    # should go away once we can upgrade to libfoo 3..
    if error_code == 42 reset_buffer()
...so that future programmers (including you) can more easily judge whether the kludge is still needed in the future.

2. Business logic. This too is difficult/impossible to discern from looking at code. Often, one's git commit history is sufficient. But there are any number of scenarios where version control history can become divorced from the code, or require a fair bit of git/hg/svn/whatever spelunking to access. And this of course becomes increasingly onerous as a module grows. If there are 200 lines of code in a given module, it is a significant time investment to go git spelunking for the origins of all 200 lines of code. Some concise internal documentation in the form of code comments can save an order of magnitude or two of effort.

    It still has problems (What do you do when the code and the 
    documentation disagree? Which is correct?), but they're not as 
    severe as the problems that arise when there is no documentation at all.
This is pretty easy to enforce at code review time, prior to merging.

In the first place, only a true maniac would intentionally update

    # no sales tax in Kerplakistan on Mondays
    return nil if country_code==56 and day_of_week==1
...without updating the associated comment. If they do neglect to update it, that's an easy catch at review time.

Re: How to Build Good Software

#62

Post by crimsonalucard »

al_form2000 wrote: post #26
crimsonalucard wrote: post #15

Nice Post. But everyone needs to understand something. Even if you follow these principles to the letter T, you can still produce very bad software. In fact you can also find many cases where people did the exact opposite of what this guy said and still produced great software. I'm sure many people can name examples of software that just came together out of blind luck. Why? Because there is no formal definition for…

We know a great deal about dynamics,kinematics, thermodynamics and generally the physics that governs car components, yet we are a long way from an algorithm that applied to a car will produce a better car. My guess is that doing that for software is as hard, if not harder. Also the sentence 'algorithms that applied to algorithms produce a better model' has a strong smell of halting problem, at least to this nose.

I get where you're coming from. I think your intuition is off.

Intuitively, software can be modeled as a graph of modules with lines representing connections between modules. An aspect of "good software" can be attributed to some metric described by the graph, let's say the amount of edges in the graph... the less edges the less complex. An optimization algorithm would probably take this graph as an input and output a graph that has the same functionality but less edges. You can call this a "better design." This is all really fuzzy and hand wavy but if you think about it from this angle I'm pretty sure you'll see that a axiomatic formalization can be done along with an algorithm that can prune edges from a graph (or in other words, improve a design by lowering complexity)

A computer program is a machine that translates the complexity of the real world into an ideal system that is axiomatic and highly, highly simplified. Such a system can be attacked by formal theory unlike real world issues like what constitutes a good car.

Re: How to Build Good Software

#63

Post by coldtea »

lifeisstillgood wrote: post #21
wenc wrote: post #16

Earlier quoted context omitted.

Also, his brother Li Haoyi wrote Ammonite, a well-known Scala REPL.

Sorry - the son of Singapore's Prime Minister is a Scala Hacker ... I keep on saying that Software Literacy is a real thing. And that this current generation of leaders are like Charlemagne - he was the first Holy Roman Emperor and the last who was illiterate. Interesting to see it in practise

>I keep on saying that Software Literacy is a real thing. And that this current generation of leaders are like Charlemagne - he was the first Holy Roman Emperor and the last who was illiterate.

And probably he was the best of what followed as well, so this literacy thing didn't go as well, where power figures were concerned...

Re: How to Build Good Software

#64

Post by ivanhoe »

clumsysmurf wrote: post #42
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…

> "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…

I've been on a couple of projects like that, and in my experience the real reason behind this logic is that manager and product owner this way may make themselves indispensable, they can't ever get fired without practically killing the project (until it becomes completely unmaintainable and slowly dies off)

Re: How to Build Good Software

#65

Post by solveit »

bsder wrote: post #54
solveit wrote: post #20

Earlier quoted context omitted.

A quasi-Orwellian dystopia Singapore may be, but their government is effective.

Only for certain strained definitions of "effective". And, if you are on the wrong side, it is very "effective" at ruining your life. Most of us would take a bit less "effective" in order to avoid that, thanks.

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?

Re: How to Build Good Software

#66

Post by koevet »

The article lists the characteristics of a good engineer:

  * has a better grasp of existing software they can reuse
  * (has) a better grasp of engineering tools, automating away most of the routine aspects of their own job
  * design systems that are more robust and easier to understand by others
  * the decisions they make save you from work you did not know could be avoided
I obviously concord with the analysis (not sure about the 10X myth). It also states that:

  * Google, Facebook, Amazon, Netflix, and Microsoft all run a dizzying number of the largest technology systems in the world, yet, they famously have some of the most selective interview processes
This sounds a bit like a paradox to me. Given the current state of "selective interview processes" (algo riddles, whiteboard coding, etc.), none of the above traits can be easily evaluated in a candidate during an interview. On the other hand, these companies do hire stellar engineers: the technological supremacy of FAANG is irrefutable.

Re: How to Build Good Software

#67

Post by irishsultan »

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…

While I still would add a comment about the why, your last bit of code probably should be written without magic constants.

    # Some countries have sales tax rules dependent on the day of the week
    return nil if country_code==KERPLAKISTAN and day_of_week==MONDAY
The exact comment here could probably be more specific (e.g. where do you find these rules), but it also most likely shouldn't repeat the code (and the code should make clear what it represents).

Re: How to Build Good Software

#68

Post by JohnBooty »

akersten wrote: post #5

One of the principles the article highlights is that additional features make a software complex and therefore more likely to fail. This is true, but I'd argue it's not for the reason the article claims. The claim is: > Stakeholders who want to increase the priority for a feature have to also consider what features they are willing to deprioritise. Teams can start on the most critical objectives, working their way do…

    I argue that it's not time constraints that complex programs bad, 
    but instead the mere act of thinking that throwing more developers 
    at the work will make it any better.
The bit about throwing more developers is true, but really does not follow from anything else you or the author is talking about.

    Treating the application as a "todo list" rather than a clockwork 
    of engineering makes a huge difference in the quality of the work. 
    When developers are given a list of customer-facing features to achieve, 
    more often than not the code winds up a giant ball of if-statements 
    and special cases.
Admittedly, this is often the case when doing feature-driven development.

But it absolutely does not need to be the case.

If you treat engineers as interchangeable cogs who only need to know about one story at a time, and never tell them about the medium- and long-term goals of the business and the application? Then yes. Then you get an awful code base with tons of if-then crap.

However, it doesn't need to be this way. If you give engineers visibility into (and some level of empowerment with regard to) those longer-term goals, they can build something more robust that will allow them to deliver features and avoid building a rickety craphouse of special cases.

I have experienced both scenarios many times.

Re: How to Build Good Software

#69

Post by hnick »

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…

Count me in as another old timer who agrees. I had a friend once throw the "code should be self-documenting" line at me once and it upsets me. That only really applies for code that is so simple it writes itself, and never has any gotchas hiding (and which useful project is like that?).

Leaning towards commenting "why" not "what" is another good general rule. "Self-documenting code" with sensible function and variables names and logical flow already cover the "what" fairly well.

Re: How to Build Good Software

#70

Post by hnick »

9nGQluzmnq3M wrote: post #14

The article appears to be written by Singaporean prime minister Lee Hsien Loong's son, Li Hongyi. http://theindependent.sg/li-hongyi-singapore-has-a-lot-of-pr...

Now I'm wondering why the children romanized their surname as Li not Lee.

I came across this article: https://mothership.sg/2015/03/lee-hsien-yang-reveals-the-sto...

> I have taught my children never to mention or flaunt their relationship to their grandfather, that they needed to make their own way in the world only on their own merits and industry.

Post reply on HN