On 10/8/11 9:20 AM, Sébastien Brisard wrote: >> I would encourage you, though, to add as much inline, class and >> javadoc documentation as possible, since that is what developers >> looking at the source will see immediately. >> > Yes, I had second thoughts on putting the notes in an external file... > The main benefit being mathematical formatting... I guess something > like alpha[k] instead of $\alpha_k$ would still be readable (and > understandable), and could be inlined in the code. It's probably the > best option. My worry is, as I said, the fact that in iteration k+1 of > the loop, we compute gamma[k-1], but also alpha[k]... It's all a bit > confusing, one has to be very careful about indices... Saunders did a > marvelous job, and the code works brilliantly in Java now (passes all > original tests by Saunders, plus additional ones, plus very large > test-cases at work). However, it was written in a very linear fashion, > with a rather large main loop. I've tried to break up the code in > smaller pieces, factor out some duplicate code, reduce the scope of > variables... But one still has to be *very* careful about these > painful mixed indices... I do think that maintenance would benefit > from additional notes, so I'll wait a while before I commit it. > > FURTHER QUESTION: do you think that this reformatting of the code > (plus renaming of some variables) could be offensive to the original > developer? Should I be careful with that? His original contribution is > fully aknowledged anyway.
The only reason to preserve original names is to make comparison with the original easier. Same applies to formatting and structure. We should be aiming for maintainable Java code, with as clear documentation as we can get of how the algorithm works and how the code implements the algorithm. Fortran structure, naming, etc., should (with great care, incrementally, etc.) be replaced by what developers expect to see in Java (preserving performance and accuracy). Phil > > Sébastien > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
