Again, I 100% agree! For functions that are self-explanatory, there is no need for documentation =)
There is a special case where I disobey this rule. That is when it seems like it is self-explanatory but it actually isn't. When wrapping system-level databases that has its own set of rules that you have no control over, I write extensive documentation to ensure that consumers of the property/function are aware of those rules.
For example,
/**
* The name that should be used to display the (raw) contact. This is the unstructured component
* of the name should be consistent with its structured representation.
*
* The [displayName] is the unstructured representation of the name. It is made up of structured
* components; [prefix], [givenName], [middleName], [familyName], and [suffix].
*
* ## Insert/update operations
*
* You have three different options when inserting/updating a [NameEntity],
*
* 1. If the [displayName] is null and there are non-null structured components provided (e.g.
* [givenName] and [familyName]), the Contacts Provider will automatically set the
* [displayName] by combining the structured components.
*
* 2. If the [displayName] is not null and all structured components are null, the Contacts
* Provider automatically (to the best of its ability) sets the values for all the structured
* components.
*
* 3. If the [displayName] and structured components are not null, the Contacts Provider does
* nothing automatically.
*
* #### Important things to know about
*
* If your app only allows users to update the structured components and not the combined
* [displayName], you should set the [displayName] to null when performing an update. This means
* **option 1 is for you**. Otherwise, if you are trying to set all structured components to
* null but you leave the [displayName] not null, the Contacts Provider will automatically set
* the value(s) of the structured components to a derived value from the [displayName]. In
* effect, your app would seemingly not allow users to clear the name.
*
* If your app only allows users to update the [displayName] and not the structured components,
* you should set the structured components to null when performing an update. This means
* **option 2 is for you**. Otherwise, if you are trying to set the [displayName] to null but
* you leave the structured components not null, the Contacts Provider will automatically set
* the value of the [displayName] to a combined value from the structured components. In effect,
* your app would seemingly not allow users to clear the [displayName].
*
* If you want to manually update both the [displayName] and structured components with your own
* custom algorithm, you may do so at your own discretion =)
*
* ## [ContactEntity.displayNamePrimary] vs [Name.displayName]
*
* The [ContactEntity.displayNamePrimary] may be different than [Name.displayName]. If a [Name]
* in the Data table is not provided, then other kinds of data will be used as the Contact's
* display name. For example, if an [Email] is provided but no [Name] then the display name will
* be the email. When a [Name] is inserted, the Contacts Provider automatically updates the
* [ContactEntity.displayNamePrimary].
*
* If data rows suitable to be a [ContactEntity.displayNamePrimary] are not available, it will
* be null.
*
* Data suitable to be a Contacts row display name are;
*
* - [Organization]
* - [Email]
* - [Name]
* - [Nickname]
* - [Phone]
*
* The [ContactEntity.displayNamePrimary] is automatically resolved by the Contacts Provider. It
* may not be manually modified.
*/valdisplayName:String?
Without the documentation above, I feel like users of this property will make mistakes and create bugs. Actually, the reason why I have so much documentation on this one property is because I encountered a head-scratching bug with it.
In any case, you are correct. There is no need for documentation on self-explanatory code.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Again, I 100% agree! For functions that are self-explanatory, there is no need for documentation =)
There is a special case where I disobey this rule. That is when it seems like it is self-explanatory but it actually isn't. When wrapping system-level databases that has its own set of rules that you have no control over, I write extensive documentation to ensure that consumers of the property/function are aware of those rules.
For example,
Without the documentation above, I feel like users of this property will make mistakes and create bugs. Actually, the reason why I have so much documentation on this one property is because I encountered a head-scratching bug with it.
In any case, you are correct. There is no need for documentation on self-explanatory code.