10 ms·

As the creator of a reasonably complex open-sourced research simulation code, I can point out a drawback with open-sourcing: The more successful you are, the mo

by lutorm 18y ago

As the creator of a reasonably complex open-sourced research simulation code, I can point out a drawback with open-sourcing: The more successful you are, the more emails you will get with questions etc and responding to them can easily take quite a lot of time away from your real work. Of course, in that this is an increased incentive to document your code extensively, it might be a good thing, too... ;-)

jrockway 18y ago
responding to them can easily take quite a lot of time away from your real work After writing a book about an open-source project, I get a lot of questions by e-mail. My usual answer is "Ask the mailing list." This is much better for everyone -- the answer becomes google-able, and they can draw from the experience of the entire community, not just me.
- hhm 18y ago
  Yes, I think the answer to the "too much mails" problem is opening a mailing list or forum. It works for medium to big projects, but for small ones I'm not sure it would be enough.
palish 18y ago
Cool! Which simulation did you create? I couldn't agree more that it's very beneficial to thoroughly document your code. If you're curious, here's a snippet I wrote yesterday to tokenize a .X geometry file: http://pastebin.com/f74646d17 http://pastebin.com/f74646d17 .... that type of aggressive source-code documentation is how I write all my code. My process is basically to write each function's entire algorithm in English, then to write the actual code. The result is "free" source code documentation. I also don't lose any productivity doing that. Just the opposite... I'm certain that it's more productive to write each function in that way, because I am constantly spotting bugs while writing the pseudocode that I otherwise wouldn't have caught until runtime. It's very easy to "misspeak" in C++. It's not a very good language for communicating concepts. But English is, and so by describing the same concept in both languages, you end up simplifying your ideas more than you would by just "speaking in one language". The result is usually a much simpler algorithm. Unfortunately, the misconception that "writing comments makes you less productive" combined with the (valid) argument that "good code documents itself" makes this style of writing source code less than popular. But oh well, at least I can benefit from it, and maybe someone else will try it.
- brentb 18y ago
  I agree that it's very easy to "misspeak" in C++ or C. It's even easier to mislead or obfuscate what's going on (i.e. write correct code that others can't easily understand). So this sort of documentation is great and I applaud you for adopting it. That said, the fact that such extensive documentation is necessary (or at the very least nice) suggests to me that you'd be better off using a cleaner, more powerful <http://www.paulgraham.com/power.html&#62 http://www.paulgraham.com/power.html> language that: (1) documents itself to some degree through more elegant syntax (2) takes care of low-level tasks that clutter and confuse otherwise clean code (resource allocation, memory management, etc.) and (3) requires less code to do the same thing, which means fewer lines to document. There are a bunch of great languages out there that are far more powerful (in terms of abstraction) than C++ or C. Haskell, Lisp, ML, F#, to name just a few. You might consider checking some of these out if you haven't already.

by lutorm 18y ago

jrockway 18y ago

responding to them can easily take quite a lot of time away from your real work After writing a book about an open-source project, I get a lot of questions by e-mail. My usual answer is "Ask the mailing list." This is much better for everyone -- the answer becomes google-able, and they can draw from the experience of the entire community, not just me.

hhm 18y ago
Yes, I think the answer to the "too much mails" problem is opening a mailing list or forum. It works for medium to big projects, but for small ones I'm not sure it would be enough.

palish 18y ago

Cool! Which simulation did you create? I couldn't agree more that it's very beneficial to thoroughly document your code. If you're curious, here's a snippet I wrote yesterday to tokenize a .X geometry file: http://pastebin.com/f74646d17 http://pastebin.com/f74646d17 .... that type of aggressive source-code documentation is how I write all my code. My process is basically to write each function's entire algorithm in English, then to write the actual code. The result is "free" source code documentation. I also don't lose any productivity doing that. Just the opposite... I'm certain that it's more productive to write each function in that way, because I am constantly spotting bugs while writing the pseudocode that I otherwise wouldn't have caught until runtime. It's very easy to "misspeak" in C++. It's not a very good language for communicating concepts. But English is, and so by describing the same concept in both languages, you end up simplifying your ideas more than you would by just "speaking in one language". The result is usually a much simpler algorithm. Unfortunately, the misconception that "writing comments makes you less productive" combined with the (valid) argument that "good code documents itself" makes this style of writing source code less than popular. But oh well, at least I can benefit from it, and maybe someone else will try it.

brentb 18y ago
I agree that it's very easy to "misspeak" in C++ or C. It's even easier to mislead or obfuscate what's going on (i.e. write correct code that others can't easily understand). So this sort of documentation is great and I applaud you for adopting it. That said, the fact that such extensive documentation is necessary (or at the very least nice) suggests to me that you'd be better off using a cleaner, more powerful <http://www.paulgraham.com/power.html&#62 http://www.paulgraham.com/power.html> language that: (1) documents itself to some degree through more elegant syntax (2) takes care of low-level tasks that clutter and confuse otherwise clean code (resource allocation, memory management, etc.) and (3) requires less code to do the same thing, which means fewer lines to document. There are a bunch of great languages out there that are far more powerful (in terms of abstraction) than C++ or C. Haskell, Lisp, ML, F#, to name just a few. You might consider checking some of these out if you haven't already.