It is known as a wart.
From a comment on the original post on Stack Overflow,
To be clear, this is not desired behavior, although there are good (historical) reasons for it. We (numpy devs) have preliminary plans to deprecate it in a future release, and provide easier to understand functionality that works as you might expect. See http://github.com/numpy/numpy/pull/6256 for more details. -- Stephan
Every design decision is a trade off somewhere. Make something simpler somewhere, and somewhere else something may become more complicated.
Consider this bit of JavaScript:
>>> '5' + 3 - 3
50
>>> '5' - 3 + 3
5
Is that a bug? No. Is it desired behavior... eh... I don't want to say people want it to work that way, but that's what you get with the 'this is how it was decided + works.'
Or in ruby that x?2:3 is a syntax error (it needs to be x ?2:3 - notice the space). Why? Because it was decided functions may end in a ? and so x?2:3 is ambiguous - a space between the variable and the ? part of the ternary expression resolves that.
Or in PhP the decision to mimic Perl's auto-increment feature on Strings but lacking the restriction on the pattern leads to:
$foo = "3d8";
echo "$foo\n";
$foo++;
echo "$foo\n";
$foo++;
echo "$foo\n";
$foo++;
echo "$foo\n";
(ideone)
printing out:
3d8
3d9
3e0
4
And without too much difficulty one could probably find examples of design warts in libraries and languages across the entire spectrum of software that were made that had unintended that had unintended and possibly undesired but nonetheless expected behavior.
There were indeed (debatably) good historical reasons the design decisions to make it work a certain way. And the code works that way - its not a bug, it is working exactly as intended. With the benefit of hindsight, maybe those decisions weren't good and lead to undesired behavior, but the code is working as intended - there isn't a bug there, its a wart.
While I have listed a few warts that I can quickly show and tickle, there are countless ones out there. I really don't need more examples. I would frankly be surprised if one were to find a language or library that doesn't contain a wart.
It depends on who the audience of a bug report is.
If it is only looked at internally by developers, to know what needs to be fixed, then don't bother. It's just noise at that point.
Non-exhaustive list of reasons to log anyway:
- Release-notes include information about fixed bugs (to some threshold which this bug meets) - especially if there is a vulnerability exposed by this bug
- Management wants a notion of "Time spent bugfixing" / "Detected bug count", etc.
- Customers can see the current state of the bugtracker (to see if their issue is known about, etc.)
- Testers get information about a change that they should test for.
Best Answer
To put bug analysis in there is a good practice, for the reasons you mentioned (just avoid being overly verbose).
This way, people reading it (including your future self) would know how much tricky the issue was and how much effort went in analysis and findings. Also, this way simplifies maintenance in the case when further changes are required related to your fix, because one could read bug report and understand why things were changed one or another way.
Just don't expect this to directly make you get noticed by higher management, because this is a different matter, a matter of workplace visibility, and this would require other skills and approaches. For the purpose of visibility, details you put into bug reports play only auxiliary, secondary role, allowing you to quickly find and get these details when necessary. Being capable to quickly pull out a clear explanation for tricky technical matters may give one a certain edge visibility wise, but it does not guarantee a major advantage.
To put fix code (except for snippets that are relevant in your analysis) into a bug report is another matter, typically a bad practice, as it is expected to be in VCS.
Good issue trackers integrated with VCS can even automatically refer readers to changes related to the fix. For an example on how this could be, take a look on Integrating JIRA with Subversion: