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

91–100 of 166 posts

Re: Software engineers should write

#91

Post by k-mcgrady »

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…

>> "Even though Steve Jobs said people don't read"

Source on this? As a general statement that sounds kind of ridiculous. I would have thought people are reading more than ever considering how much of the internet is text. Also a little strange considering Apple runs a bookstore.

Re: Software engineers should write

#92

Post by LVB »

henryw wrote: post #42

I've always admired the writing style in the Economist: http://www.economist.com/styleguide/introduction

Because of my own ignorance, I'd assumed The Economist Style Guide was another tome mainly full of usage rules. Having actually looked at a bit of it now, it seems much more accessible and useful than that.

Re: Software engineers should write

#93

Post by tooatui »

Writing is never easy for me even in my first language. I guess I am one of those "math kids", but some part of me wants to write, to express myself, to make an impact. I do become better at writing after a few blog posts in Chinese, and I will start to write in English, because I think English is such a beautiful language and after so many years of studying, writing might be the way for me to truly understand and use it.

Re: Software engineers should write

#95

Post by amelius »

> Software engineers should write because it promotes many of the same skills required in programming.

The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other.

> Code and essays have a lot more in common.

What I hate about writing prose, is that you are expected to use synonyms all over the place. If you use the same word in two subsequent sentences, this is considered "bad". With programming, I have no such problem.

Re: Software engineers should write

#96

Post by iancw »

tjradcliffe wrote: post #82
las_cases wrote: post #33

Earlier quoted context omitted.

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.

Code doesn't capture intent in many critical cases, so figuring out what a piece of code is supposed to do is different from figuring out what it does. This is true in part because there are very different levels of abstraction involved. To take a trivial example: norm = sqrt(x[0] 2 + x[1] 2 + x[2] 2) x[0] /= norm x[1] /= norm x[2] /= norm This could be described as "take the square root of the sum of three values an…

> but now you have a function call per renormalization and that has a cost that may be unacceptable.

I would go for the function, and pass along Knuth's advice about premature optimization. If you're writing at such a low level that function calls actually aren't acceptable, go with a comment "// renormalize vector." Your instinct should be the function though. I bet there is more than one vector normalization going on in this hypothetical codebase, and that line looks pretty typo-prone.

Re: Software engineers should write

#97

Post by Kalium »

robbrown451 wrote: post #41
Kalium wrote: post #3

I find myself uncertain about the thesis. Code that is clear and expressive to a human should not be assumed to also be efficient and optimal for a computer. As writers say, know your audience.

I didn't see what you are seeing in the thesis. There was nothing that said that the sole end goal of programming is to be expressive to humans (whether those humans be yourself, other coders or end users). As for audience, when coding you can consider your audience to be both humans that follow you, as well as the machine it is running on.

One of the ideas mentioned is that code that's readily understood by humans is code that will be efficient for computers. I'm not sure I agree with this.

Re: Software engineers should write

#98

Post by superuser2 »

amelius wrote: post #95

> Software engineers should write because it promotes many of the same skills required in programming. The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other. > Code and essays have a lot more in common. What I hate about writing prose, is that you are expected to use synonyms al…

>If you use the same word in two subsequent sentences, this is considered "bad"

It depends. We are explicitly taught to do this in philosophy papers - be clear about what your terms mean, and then always use the same term when you mean the same thing.

Re: Software engineers should write

#99

Post by blister »

StavrosK wrote: post #75
sophacles wrote: post #57

Earlier quoted context omitted.

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

That's a good outlook. I can't tell you how much it irks me when someone is annoyed that someone else doesn't speak English well. I always say "at least their English is better than your ". Invariably, that outlook is expressed by people who happen to only speak one language.

I don't mind when I meet someone in normal daily activities that speaks English poorly. My thoughts on the subject mirror your own.

What _IS_ frustrating is dealing with a customer service representative in an overseas call center that speaks English poorly. How many man hours have been lost in forced communication with foreign contractors in an effort to save a few dollars an hour over an American counterpart? Also, those cost savings to a company like Comcast also damage our economy by not employing Americans in need of work. It's a double-whammy of frustration.

Re: Software engineers should write

#100

Post by ghaff »

amelius wrote: post #95

> Software engineers should write because it promotes many of the same skills required in programming. The problem with writing is that you usually do it by serializing your thoughts in one go. Programming on the other hand is an activity where you almost randomly jump from one point to the other. > Code and essays have a lot more in common. What I hate about writing prose, is that you are expected to use synonyms al…

>The problem with writing is that you usually do it by serializing your thoughts in one go.

Depends on the person and the circumstances. I admit that I tend to write linearly as a first pass and the writing is often an act of discovery--although I generally have some idea of my (intended) destination when I begin. That said, I'll often craft sections semi-independently and "glue" them together after the fact. I think I see more structural and process similarity than you do.

Post reply on HN