3 ms·
what is "set point"? Is it a point that is a part of some kind of set? What's "point" - is it part of some kind of coordinates? You are documenting _what_. To
by watt 5y ago
what is "set point"? Is it a point that is a part of some kind of set? What's "point" - is it part of some kind of coordinates?
You are documenting _what_. To document _why_, you must explain why somebody would want to change the "set point" and what is the effect, and not in terms that "setA sets a", but the semantics of it. What does setting point accomplish? What are the circumstances when you want to do it? _WHY_ would somebody want to call this method?
Make the room colder? Make the room hotter? That kind of thing.
- jdlshore 5y agoYou have to assume a certain amount of domain knowledge, or you end up explaining the entire universe. In this case, "set point" is a well-understood term, and its purpose is similarly well-understood. [1] Although the team may wish to document it, the place to do so is in the team glossary (or other overview documentation), not in every function that uses it. [1] http://faculty.washington.edu/brengelm/neut_zone/pg3.html http://faculty.washington.edu/brengelm/neut_zone/pg3.html
- watt 5y agoThanks for info, I did not know it's a common industry term! Anyway, the point I am driving is, it's more interesting to discuss _why_ would anyone change the "set point" - common scenarios and pitfalls, than just explaining the "update_set_point changes the set point". It's nice to go into details what are the consequences and common use-cases.