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

Software engineers should write

shubhro.com

Post reply on HN
Print view View original

51–60 of 166 posts

Re: Software engineers should write

#51

Post by marktangotango »

las_cases wrote: post #33
marktangotango wrote: post #21

Hey software engineers, write some m*ther f!cking documentation! Don't tell me it goes out of date, at the very least a module level, architectural overview is better than nothing, and should remain relevant past your tenure. /rant

How do you feel about the saying that code itself should be as good as documentation? I personally prefer to read the documentation while skimming the code as well but sometimes, when I am under the pressure of having to deliver something, I absolutely despise not having proper documentation so I tend to agree with you.

>> How do you feel about the saying that code itself should be as good as documentation?

The truth is, 95% of developers do not write readable code. But I've been doing this for a while, so I can follow pretty much anything. It's the shear volume of legacy code in the typical code base thats the problem.

What kills me is dead code that you don't know is dead; hundreds of class files, dto's, booleans passed around to control processing that are always false now, because that alternate path is no longer used. And protocol messages, oh god the hundreds of protocol messages, but we only use 10 now.

Edit; I've been the hero more than once documenting stuff like the above.

Re: Software engineers should write

#53

Post by sophacles »

edpichler wrote: post #23

"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN ( https://news.ycombinator.com/item?id=5614689 ) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thi…

Tangential - Just want to give you some feedback on your comment, since you are wanting to improve your second language:

First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts and a proof-reader).

Second: You're doing commas better than a lot of native english speakers. That's pretty impressive.

Third: There are a couple of grammatical/phrasing errors I'll tell you about in your comment. These are really common errors amongst people who learn English as a second (or Nth) language, and I'm not doing it to belittle you, but to help your stated goal of improvement.

I'm doing it since 09/22/2014

This is one of those wierd places in English where the verbs "to do" or "to be" combine strangely with tenses and idioms. I'm not so sure of the technical way of stating the problem, but here's a couple of examples of a more natural way to state it:

* I've been doing it since 09/22/2014.

* I've done it since 09/22/2014.

but something in me tell me that

This is a small one, and maybe a typo, but it is part of a pattern I've seen a lot. Again, not great at the technical grammar terms, but it should be:

* but something in me tells me that

(notice the 's' on tells).

Anyway I'm always impressed with people who can learn a second language well, and wanted to encourage it and help if can.

Re: Software engineers should write

#55

Post by edpichler »

sophacles wrote: post #53
edpichler wrote: post #23

"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN ( https://news.ycombinator.com/item?id=5614689 ) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thi…

Tangential - Just want to give you some feedback on your comment, since you are wanting to improve your second language: First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts a…

Oh, I really appreciate your corrections, thank you! I understand that reading bad English is really annoying for natives. I try to be careful here on HN, but sometimes I do some mistakes.

Re: Software engineers should write

#56

Post by mirkoadari »

joeblau wrote: post #38

I write a blog[1] and I try to add good documentation to my open source project[2], but I recognize that I'm in the minority. One benefit I get from writing, even though I don't get a lot of readers, is thought refinement. I usually send my blog posts to friends and family for help on word choice and better delivery. Even though Steve Jobs said people don't read, I think reading and writing are critical because you d…

Wow, gitignore is an OSS project?! Didn't know this. Are you looking for collaborators? Love your project and have been looking for something to tinker with on free time. Kudos for great work!

Re: Software engineers should write

#57

Post by sophacles »

edpichler wrote: post #55
sophacles wrote: post #53

Earlier quoted context omitted.

Tangential - Just want to give you some feedback on your comment, since you are wanting to improve your second language: First: you've overcome a big hurdle in learning a second language, I understood what you are trying to communicate, and I did so on my first reading of it. To me, this means you're already good at english! (By comparison if I tried in my second language, which is German, I would need a few drafts a…

Oh, I really appreciate your corrections, thank you! I understand that reading bad English is really annoying for natives. I try to be careful here on HN, but sometimes I do some mistakes.

You're welcome. Personally, I don't understand when people get annoyed by those things. I figure if someone has done me the favor of learning my language to communicate with me, and they've done so well enough that I understand them, why should I nitpick little errors?

I only point out things like this to people who state they are actively trying to improve - because they've done me a favor by being able to communicate with me, and I can return it by helping them at their goal.

Re: Software engineers should write

#58

Post by dataphile »

Thanks for posting this, it is very timely for me. I have been a forum lurker for most of my life. I visit Hacker News almost everyday but seldom do I post a comment and I have never submitted an article. Same with Facebook, I'm mostly a lurker. It is my New Year's resolution to start writing and contributing more to the online communities I visit. In fact I just finished my first draft of a blog about my experience using Angular, LokiJS, and Ionic to make offline apps. Hopefully in the next day or two I will publish it on my blog and maybe even submit it to Hacker News. Your blog posts encourages me to keep at it. Thanks.

Re: Software engineers should write

#59

Post by edpichler »

ionforce wrote: post #47
edpichler wrote: post #23

"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN ( https://news.ycombinator.com/item?id=5614689 ) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thi…

> I'm doing it since 09/22/2014. "I've /been/ doing it since ..." Concordo. Acho que deve continuar escrever. De onde você é? I agree. You should continue to write. Where are you from?

Brazil.

Re: Software engineers should write

#60

Post by ivansavz »

kalid wrote: post #24

I've always been a fan of Einstein's quote "If you can't explain it simply, you don't understand it well enough." Writing about a topic is a good test of whether you can explain it simply.

In "physics land" Richard Feynman is famous for his explanatory power, e.g. We tried to take advantage of Richard's talent for clarity by getting him to critique the technical presentations that we made in our product introductions. Before the commercial announcement of the Connection Machine CM-1 and all of our future products, Richard would give a sentence-by-sentence critique of the planned presentation. "Don't say `reflected acoustic wave.' Say [echo]." Or, "Forget all that `local minima' stuff. Just say there's a bubble caught in the crystal and you have to shake it out." Nothing made him angrier than making something simple sound complicated.

via http://longnow.org/essays/richard-feynman-connection-machine...

Post reply on HN