Reminds me of this style: /** * Calculate the thing. * * @param $foo the foo value * @param $bar the bar value * @return the thing */ fun

Reminds me of this style: /** * Calculate the thing. * * @param $foo the foo value * @param $bar the bar value * @return the thing */ function calculateThing($foo, $bar) { return $foo + $bar; // add foo and bar } Such comments are worthless noise that obscures the important parts of the code and camouflages any actual useful comments that might be there. I would so much rather have better names than "thing", "foo", and "bar", and maybe a comment about why the values are summed, if it's not obvious. When you do those right, you won't even need many comments. Maybe a docblock, but don't bother with that if it's nothing more than a robotic "English version" of what is already obvious from the function definition. IMO most good developers will perceive your file header as a redundant annoyance for similar reasons, as other commentors have explained.