81–90 of 166 posts
Earlier quoted context omitted.
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.
Your English is not "bad". There are some technical grammar issues you'll continue to work out, but the meaning in your writing is perfectly clear. That makes it pretty easy to overlook anything that's not quite correct in your writing.
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.
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 and then divide each value by the result" or "renormalize a vector". The latter is by far the more meaningful and useful description because it is presented at the level of abstraction that the user is likely interested in.
You could say "well why not create a function called 'renormalize_vector' so it would be self-documenting?" Fine, but now you have a function call per renormalization and that has a cost that may be unacceptable. For many simulations renormalizing vectors with a norm near unity is a big overhead, to the extent that I've written custom code to handle that special case and implement it as a macro that I could call "FAST_RENORM_NEAR_UNITY"... but what does "near unity" mean? And what trade-offs went into the design choices? What code isn't there because I tried it and it didn't work well?
People who advocate self-documenting code generally talk as if self-documenting techniques come at zero cost (adding a function call is an unacceptably high cost in some cases) and that the code that exists adequately captures all the thinking that went into it (it does not and cannot.)
So while I'm all for as much self-documentation as possible, any non-trivial code is going to require additional documentation to a) describe the purpose in high-level terms and b) capture the alternatives that were rejected and why.
Unfortunately, for open source projects especially, there is a law of documentation that says power*documentation=constant, so the most powerful code has the worst documentation, and there are projects with great documentation that simply don't do much.
"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…
> > 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,
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…
A further advantage: such comments have longer halflives. A rewritten method may still have the same purpose long after all details are changed.
I was always an "English kid", came close to failing my math subjects in middle school and finally in high school, I did fail Algebra I, and had to re-take it the next year. Meanwhile, I was in advanced programming courses and on my way to take an AP Computer Science course in the last semester of my sophomore year. Looking back, that experience taught me about how important modeling is to pedagogy. The fact is, my A…
I did very well at English at school, but failed hard at maths whilst freelancing from home after teaching myself PHP.
I really wish I'd engaged (and was taught) maths in the same way as I did with code - I remember feeling quite annoyed at the way I was being taught maths which was basically "when you see a question asked in this way, you answer it by following these steps". I think if I'd been taught maths through experimentation and having "projects" to solve in the same way I learned to code, I would've been quite a good maths student.
1) their writings will be preserved with the same power that libraries afford traditional scientific publishing
2) They wont just be blogging, they will be publishing.
3) They can assign a digital object identifier (DOI) at their discretion making their work "count" in the scholarly literature.
4) Their blog will be automatically formatted as a PDF.
5) https://thewinnower.com/papers/science-the-pursuit-of-the-tr...
6) https://thewinnower.com/papers/making-scientific-blogging-co...
Earlier quoted context omitted.
> Looking back, that experience taught me about how important modeling is to pedagogy. Very good point! This is the strongest "pitch" for why one should learn math: the modelling superpowers one will acquire. Every function f(x) is a type of model (e.g. mx+b, x^2, e^x, ln(x), cos(x), |x|, etc.), and understanding the function f(x) will allow you to model any phenomenon that exhibits f(x)-like behaviour. [note: I'm wo…
"gain modelling superpowers" makes no sense to someone who doesn't already understand what modelling is and how is can be used. It is also a comical idea to try to market a book toward students these days - getting even a high school student to read anything longer than a few sentences in one sitting is a miracle.
I agree with you generally, but if you compare with the current math textbooks (that students are usually forced to buy) you will concede there is a lot of room for improvement on the textbook side.
Also, while I think technology might be cool to play with, nothing beats the book as a medium for the transmission of information.
Which in a way helps prove one of the article's points: writing and programming are alike in their need for precision and clarity. :)