Usually there is an @author tag in API documentation (JavaDoc, PHPDoc etc). Is it acceptable to use this tag on every function you make in a commercial product?
0
The author tag may serve two purposes:
- Claim code ownership
- Provide a point-of-contact for future code maintenance needs
Purpose 1 may be a legitimate use for some projects, but its use must be governed and enforced by the project team. For commercial closed-source project, it is likely that this usage could be forbidden.
Purpose 2 may serve a legitimate, yet transient (temporary) need to help establish multiple points-of-contact in distributed teams that don’t normally communicate. In other words, teams that had broken or non-existent communication channels, and missing some standard software development practices. Putting that information in a project wiki, or ensuring that source control commit history is accurate and accessible to everyone (developers as well as API users), will be a better alternative.
Consult with project lead if you encounter this tag in existing code, to see whether it should be kept or removed.
If you see this tag that refers to a person not in your company, it may be a sign of improper code appropriation (e.g. stealing code from other sources without attribution and/or licensing), which is a different and much bigger issue.
Heh, I never thought that by using the @author tag I was claiming ownership of the code, in my mind it was more of a “if this breaks, blame me” comment. I’ve long given up on writing such comments though, version control is my preferred way of finding who to blame when stuff break.
If you must show code ownership in the legal sense, then have your @author tag in the page/class level DocBlock, and don’t forget to point to the code’s license with the @license tag.
0