Take the 2-minute tour ×
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.

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?

share|improve this question
add comment

2 Answers

up vote 5 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.