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?


The author tag may serve two purposes:

  1. Claim code ownership
  2. 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.

| improve this answer | |

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.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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