Hacker News Reader

Comment by calpaterson | Hacker News Reader

Author here, I can't reply to the GP because that comment is "dead" but yes, please, be specific!

Then I can fix the sentences that are bad and perhaps also improve in the future.

"Even though the file API handles all those concerns, but it doesn't expose them to you. A narrow interface handling a large number of concerns - that makes the unix file API a "deep" module."

Both sentences here are incomplete, incoherent. I did not read past this point.

Thanks. I take your point on the first one and have corrected it (maybe you need to shift+F5 to bust your cache in order to see it).

For the second one, what's your objection? That it's fragmentary?

I don't know what it's trying to say. Making it a complete sentence would be a good first step. Don't try fancy stuff like this unless showing off style is more important to you than communicating coherently. In technical writing, little is more important than clarity.

A narrow interface handling a large number of concerns... makes the UNIX file API a "deep" module."

Seems self-explanatory to me. "Deep module" [0][1] is a well-defined term.

[0]: https://dev.to/gosukiwi/software-design-deep-modules-2on9

[1]: https://www.amazon.com/Philosophy-Software-Design-John-Ouste...

Honestly the only minor criticism I can see of the OP's writing is to remove things that make it seem more disjointed than it is - dashes, unqualified pronouns (what is "it"? AWS? UNIX file system API? a particular module? all modules?). That's all.

Thanks for your advice. I agree and will try to improve on this for the future

Reply on news.ycombinator.com