Tell me more ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 4 down vote favorite

Short Question
Is it necessary to add the function header comments for simple accessors and mutators?

Example 

u8   OBJ_get_state_x(void) {return obj.state_x;}  
void OBJ_set_state_x(u8 x) {obj.state_x = x;}

Addition Thoughts
The object (OBJ) overall contains very minimal logic (if any). Its sole purpose is to maintain the state of a system. Additional modules (such as IO, COMM, DISPLAY, etc...) all know what the object is and contain all of the business logic required to drive the states in OBJ.

I would like to keep all of the accessors / mutators on a single line to make the file a bit more readable and just put a generic block header above all of them. I just don't know if this is a common (or good) practice.

Note that all of the ranges are the bound by their type. If there is a special state that has a range of 0 to 3, I create an typedef'ed enum to use as the type (thus forcing the range and making the code more readable IMO).

share|improve this question

3 Answers

up vote 3 down vote accepted

Only if logic is performed. Its possible to have getters / setters that don't map to specific class variables, so, in this case, yes, if its just returning a class variable then no, why would this be necessary? (except for in a class teaching programming or something)

share|improve this answer
This is the approach I have taken so far. I really don't feel that the headers provide anything to code. However before dismissing them all together, I wanted to see if someone could enlighten me with a good reason for them. The college days are still fairly hardcoded (pardon the pun) in my mind regarding coding standards. – Adam Lewis Oct 2 '11 at 19:03
1  
There isn't a good reason to add additional documentation if the purpose of the getter/setter is blindingly obvious (e.g., setRadius() on a Circle). The exceptions would be if anything beyond simple assignment is done in the method or if your documentation tools don't pick up on code without comments (rare). – Blrfl Oct 2 '11 at 21:18
1  
Here's a good SO post on the topic: stackoverflow.com/questions/1568091/why-use-getters-and-setters It has mainly to do with maintaining a public interface of the class while being able to change things internally, such as if you currently have a getter / setter for a class variable called foo and later decide to get rid of that class variable you can still map the getter / setter to something else so it doesn't break that code that uses the getter / setter methods, also it enables adding in validation, if needed – programmx10 Oct 3 '11 at 0:58
also, while there may not always be a great reason in every case to use getters / setters, they have become essentially become a standard so its usually best to just use, at least for certain languages / frameworks, them unless its just a personal project that no one else is going to work on – programmx10 Oct 3 '11 at 1:00
Continuing on @Blrfl's example, a Circle's getArea() method seems to fail your "don't map to specific class variables" test, since if you have the radius you can compute the area with no trouble, so there's no reason (unless it's performance-critical) to keep the area separately from the radius. Or diameter, if you prefer that. In the case of, say, a Rectangle, getArea() would not have any direct mapping to any one member variable. – Michael Kjörling Oct 3 '11 at 11:53
show 2 more comments
up vote 1 down vote

I think you should have a comment there still, not to explain what the function itself does, which is obvious, but rather what the variable returned by it does.

If the name of the variable explains it, then fine - you probably don't need any comments. If the name is something like "state_x" the programmer calling the function is most likely interested in knowing what states there are. If the state is part of a state machine, perhaps all the states need to be explained one by one.

All of this will of course depend on what documentation you can already find elsewhere in the project: if the behavior of "OBJ" is explained elsewhere, then a list of all declarations without comments is probably a sensible solution. However, my own personal philosophy is that a programmer should be able to pick out any code module of mine and understand what it does just by reading the h-file, without the need of external documents.

And to be picky: if I encounter a non-const get member function I would expect an explanation of why it wasn't declared const. It suggests that the function isn't a simple getter, but rather that there is some sort of internal magic taking place inside that function.

share|improve this answer
up vote 0 down vote

Maybe

A comment could be useful, but someone has to write it. Generated comments are detrimental; they take up space and programmer time but say nothing. Your inclination to keep all the accessors to a single line is correct. I would be tempted to eliminate them entirely by making the data members public.

share|improve this answer
4  
there are plenty of articles out there about why making them public is a bad idea, and, at least in the Java world, this is considered bad practice and would most likely be looked at negatively by other dev's in your company – programmx10 Oct 2 '11 at 18:50
@programmx10: Looks like the OP is writing an embedded application in C. Java is a special case because it it the only popular language that does not support properties. Even then, if a class is internal to a single application, and has no behavior, then public data members may be fine. If things change, then it's no problem to make the members private, add accessors, and fix all the resulting compilation errors. – kevin cline Oct 2 '11 at 19:20
It is indeed an embedded application. The largest reason that moving them public is non-ideal, to me, is that I expect that the object will get heavy reuse. So for the next variant of the application my need to apply logic or latching mechanisms any time a state is changed. FYI, the previous version of this basically had the data public. It became tedious to maintain. – Adam Lewis Oct 2 '11 at 19:37
If you feel the need to make member variables public for a certain application, you should perhaps start to question why you are using OO for it in the first place. – Lundin Oct 3 '11 at 11:21
Btw: this has nothing to do with language nor platform, private encapsulation is an universal programming term and pretty much every high-level language support it at some level. In C it is done with static declarations. – Lundin Oct 3 '11 at 13:33
show 2 more comments

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.