14 questions
0
votes
0
answers
52
views
How to use self-docummenting equals (debugging) specifier with str.format()?
Python 3.8 introduced = specifier in f-strings (see this issue and pull request).
It allows to quickly represent both the value and the name of the variable:
from math import pi as π
f'{π=}'
# 'π=3....
- 15.7k
2
votes
1
answer
310
views
How do I tell doxygen a function is "self-documenting"?
I'm using Doxygen for my (C++) project.
I have some functions which are self-explanatory, for which I don't want to add any comment or explanation - but which I do want appearing as part of the ...
- 137k
-1
votes
2
answers
443
views
PHP: Using array keys to identify function arguments [closed]
I user-define many functions and a few of them have six, ten, or even more arguments. Reading my code gets difficult when I forget what the arguments of a function are, or what order they go in. I've ...
- 1,849
0
votes
2
answers
178
views
Self documenting asp.net api
I created an Asp.net api in VS2015. Inside the Areas>HelpPage>App_Start>HelpPageConfig.cs I uncommented line 37
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current....
- 33
0
votes
1
answer
145
views
Do the most current JavaScript/ECMAScripte compilers optimize out unnecessary variable assignment when returning the value from a function call?
Say we are inside an object that implements file handling. I want to write the code for easier readability.
Example of code where it can be difficult to tell the return type, especially when there ...
- 207
1
vote
1
answer
1k
views
Self documenting parameters in Lua
I'm looking for a way to clarify the contracts of my Lua functions. In particular, which attributes there parameters are supposed to have.
To illustrate my problem, some code snippets with typical ...
- 11k
3
votes
1
answer
1k
views
Does Kotlin have method-CALL labels?
I'm moving from Swift to Kotlin, and loving it so far. However, I'm used to declaring methods like this (pretend the referenced methods exist and work):
// Swift method declaration
func drawCircle(...
- 32.4k
5
votes
2
answers
7k
views
Jira JQL can have inline/embedded comments?
I found a good list of tutorials about JQL, including a reference on how to write a plugin [1]. Is there already or would it be possible to add comments to a JQL query?
For example, to document my ...
- 10.4k
17
votes
4
answers
15k
views
How to autogenerate API documentation from Express route mappings?
I am developing a REST API in nodejs + Express and I have been simultaneously documenting my API in the README file and I was wondering if it is possible to automate it. e.g. given:
app.get('/path/to'...
- 33.7k
4
votes
1
answer
256
views
Is self-documenting code worth potential performance issues?
I created small class that allows me to use enumerators of strongly-typed enums as flags (in combination). I'm using type_traits for underlying type detection so it should be also slightly type safe ...
- 155
2
votes
1
answer
1k
views
JavaScript Self-documenting code where's the API Docs tools?
These two concepts seem counter-intuitive. There's one side of the argument that sees the harm that comments do to readability, and violations of DRY (if the comments are even kept up to date). ...
- 4,711
1
vote
2
answers
148
views
Should method/class comments be consistently applied or on a need basis only?
For consistency, I've always applied comments (in the form of a JavaDoc) to all methods and classes, even if they are simple getters and setters methods or very small wrapper classes. But I'm also ...
- 4,848
287
votes
14
answers
197k
views
In Python, how do I indicate I'm overriding a method?
In Java, for example, the @Override annotation not only provides compile-time checking of an override but makes for excellent self-documenting code.
I'm just looking for documentation (although if ...
- 5,645
34
votes
20
answers
14k
views
Do people use the Hungarian Naming Conventions in the real world? [closed]
Is it worth learning the convention or is it a bane to readability and maintainability?
- 551