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

211–220 of 247 posts

Re: How to Build Good Software

#211

Post by dkersten »

whydoyoucare wrote: post #178
dkersten wrote: post #150

Earlier quoted context omitted.

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

If you document via design logs and decision logs, then you don't need to document every line of code because its already done in the design log. If something unforeseen arises, then you have a discussion, make note on the outcome in a decision log and move on. That is, the documentation logs proposed decisions and outcome decisions, which should contain enough context that you can read them in isolation. Then you don't need to worry about documenting as you're coding or documenting the code.

If you diverge too far from the original design, you should probably have a rationale as to why, that gets reviewed by others: another design log and decision log.

These documents don't need to be long either, just a couple of sentences for each of context, what you propose, impact on other teams or systems, decision made may be enough for smaller things (so a paragraph or two) and for larger changes, you probably need the detail for everyone to really understand what, why and its impact. The alternative is to do these things blind.

> 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.

Absolutely agreed.

Re: How to Build Good Software

#212

Post by nitrogen »

arethuza wrote: post #125
irishsultan wrote: post #67

Earlier quoted context omitted.

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

But don't do what one memorably awful project I had to maintain did - to use that example they would have done: country_code==FIFTY_FIVE and day_of_week==ONE

But how else will your compiler tell you that you mistyped 55? /s

Re: How to Build Good Software

#213

Post by cuddlybacon »

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…

> 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.

That sounds like the happy path for dealing with the Canadian government. Well, except the months part.

Re: How to Build Good Software

#214

Post by fooblitzky »

The author is very cavalier about open source licenses - they seem to be implying you can just use open source code whenever you want, even for closed-source, proprietary applications. Whether or not that is true depends on the licenses involved.

Re: How to Build Good Software

#215

Post by tempguy9999 »

Dumblydorr wrote: post #144
steventhedev wrote: post #138

Regarding "Seek Out Problems and Iterate", it's a bit of an understatement how important this is. I've invested a lot of time helping my coworkers understand the distinction between tasks and problems. The end goal being only tracking problems in the ticketing system. It's not easy to do this and it takes constant effort, but it pays off very quickly. I've yet to see a real "problem" ticket stay unresolved for a long…

Can you explain the 3pm on Tuesdays issue? My sister works for LLS and she said their servers get very slow at a precise time every Tuesday. Not saying it's the same bug, but what was the solution in your specific case?

Database doing some housekeeping or backup; virus scan; perhaps automated check for windows updates (patch tuesday is every 2nd tuesday of every month so prob not that); completely separate task fighting the DB or other application layer you sis uses. Something else. Anything else.

It's not something anyone can diagnose from what you say, it could be anything, even weirdness such as a hardware fault kicked off by something else (office cleaner plugging something in?) causing power spike RF interference affecting the network causing mass packet drops and retries (ok, unlikely but it's not impossible, I've heard of such).

Re: How to Build Good Software

#216

Post by mindcrime »

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…

They consider the User Stories + the code to be everything you need

Then they are Doing It Wrong™. Note that there's nothing in the Agile Manifesto OR the Scrum Guide that says "don't write documentation." The closest you get is in the AM where it says "We have come to value ... Working software over comprehensive documentation". But note that immediately after that it says "That is, while there is value in the items on the right, we value the items on the left more." IOW, the Agile Manifesto explicitly endorses the value of documentation!

Remember this the next time somebody tries to tell you that "we don't do documentation because we're Agile." Anybody running that line is Full Of Shit™.

Re: How to Build Good Software

#217

Post by carapace »

crimsonalucard wrote: post #210
carapace wrote: post #191

Earlier quoted context omitted.

So you're not talking about "formal methods"? https://en.wikipedia.org/wiki/Formal_methods The Applied Category Theory folks have some very interesting stuff, like Categorical Query Language. https://www.appliedcategorytheory.org/ https://www.categoricaldata.net/ But it sounds to me what you mean is more like if "Pattern Language" was symbolic and rigorous, eh?

Yes, this is exactly what I mean. Though I feel patterns can be formalized within thr framework of category theory.

Have you read "Introduction to Cybernetics" by Ashby?

(PDF available here: http://pespmc1.vub.ac.be/ASHBBOOK.html )

Cybernetics might be the "missing link" for what you're talking about.

Re: How to Build Good Software

#218

Post by bsder »

solveit wrote: post #65
bsder wrote: post #54

Earlier quoted context omitted.

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?

I replied that way because, if we moved this to a tech subject, people here would be horrified at your definition of "effective".

If someone produced an insulin pump that you implanted, worked perfectly for life, but killed 1 person in 1,000 randomly, people would be screaming for the head of the CEO of that company rather than calling it "effective".

Re: How to Build Good Software

#219

Post by mcgwiz »

The lead image features two laptops and a desktop. And three hardcopies of code. All with a light-on-dark color scheme. I'd wager they had a bit of fun taking this programmery photo.

Re: How to Build Good Software

#220

Post by Viliam1234 »

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…

> Does anyone have any suggestions on how to fix this?

Have a product wiki (e.g. MediaWiki).

Have documentation in source code that compiles to HTML code, which can be linked to/from the product wiki (e.g. JavaDoc in Java, Natural Docs for languages that do not directly support compilable documentation). Make building and publishing this documentation a part of the continuous integration.

When you have this, make it a part of code reviews to ask "where is this documented?" for those kinds of things that are easy to remember today, but no one will remember it a few months later. In other words, make it a "code+doc review".

(Don't be dogmatic about whether the information should go to code documentation, unit test documentation, or wiki. Use common sense. If it only related to one method, it's probably the code; if it related to a use case, it's probably the unit test that verifies that use case; if it is a general topic that has an impact on many parts of the program, it probably deserves a separate wiki page.)

Post reply on HN