design comments in code or in tests?
Joerg-Cyril.Hoehle at t-systems.com
Joerg-Cyril.Hoehle at t-systems.com
Fri Sep 30 11:34:26 CDT 2011
Hi,
here's another one you WineConf folks may want to discuss.
I've already expressed that there are not enough comments
in mmdevapi's code. I thought about adding some, but wondered
whether there's any value in using the header format that
old code in Wine uses/used for automated doc. Generation
(whatever the exact format was).
For instance, comments ought to document GetPosition's
contract in sufficient detail:
- 0 <= GetPosition <= sum of written samples (modulo Frequency)
- underruns don't count, it's no wall clock
- monotically increasing(?)
- should reflect speaker position, not buffering (MSDN says that)
Don't look up MSDN. If that were complete enough, I would not
have had the need to write as many tests as I did.
Then I thought about placing comments in dlls/*/tests/ instead,
because the test code is thrown away less often than the dll code.
Seriously.
Regards,
Jörg Höhle
More information about the wine-devel
mailing list