Open iansan5653 opened 4 years ago
My opinion is that if we're extending the meaning of area
, we should probably redeclare it:
/**
* A residential house that someone might live in.
*/
interface HouseB extends Building {
/**
* The number of people living in the house.
*/
residents: number;
/**
* The total area of the house in sq. ft. House area doesn't
* include garages, attics, and basements.
*/
area: number;
}
@member
seems to go against a couple of software engineering principles:
Reading > Writing: @member
is a shorthand that saves some work for the person writing the code, but at the expense of making the code harder to read. The person needs to go find the base class to figure out what area
is talking about. We should prioritize the experience of people who read code, because reading a more challenging/important activity than writing code.
One obvious way: @member
introduces with two different equivalent ways to document an inherited member. This flexibility is bad. Good flexibility is like forks versus spoons -- different tools optimized for different jobs. Bad flexibility is like Phillips screws versus flathead screws -- make everyone buy two screwdrivers for no clear benefit. 😋
I'm open to other views, though!
Sometimes you have a generic base interface type that you extend from, and you want to documenting a member of the extending interface without having to redeclare that member. In this instance, it would be useful to be able to document interface members in the interface's description. This is better explained in an example: