Stack Overflow
Stack Overflow

Questions tagged [self-documenting-code]

16 questions
258
votes
14 answers

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 it's an indicator to some checker like pylint,…
Bluu
  • 5,226
  • 4
  • 29
  • 34
34
votes
20 answers

Do people use the Hungarian Naming Conventions in the real world?

Is it worth learning the convention or is it a bane to readability and maintainability?
Brock D
  • 551
  • 1
  • 7
  • 10
15
votes
4 answers

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',…
pathikrit
  • 32,469
  • 37
  • 142
  • 221
4
votes
1 answer

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 and mostly processed at compile time. However, i…
HemoGoblin
  • 155
  • 4
3
votes
1 answer

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(inRect rect: CGRect, antialiased: Bool) { …
Ky -
  • 30,724
  • 51
  • 192
  • 308
2
votes
1 answer

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 documentation. Now, this does happen as doxygen's…
einpoklum
  • 118,144
  • 57
  • 340
  • 684
2
votes
1 answer

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). However, flip the coin and there is a necessity to…
Drew
  • 4,683
  • 4
  • 35
  • 50
1
vote
1 answer

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 structure of my current code. A function that…
Jeroen De Dauw
  • 10,321
  • 15
  • 56
  • 79
1
vote
2 answers

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 striving to write self-documenting code which often…
gablin
  • 4,678
  • 6
  • 33
  • 47
1
vote
2 answers

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 item, I'd like to be able to document that our…
AnneTheAgile
  • 9,932
  • 6
  • 52
  • 48
0
votes
0 answers

What is the type hint (or type annotation) of type hints (or type annotations)

Consider the following Code: from typing import Union # (or any other type hint, type Alias, etc.) def func(arg: ???) -> None: pass func(Union[tuple[int, ...], float, "MyClass"]) class MyClass(object): pass The argument of function…
Tom
  • 54
  • 8
0
votes
0 answers

Documenting tool for a Programming Language itself

At first I thought about using doxygen for my needs, but then I realized that would be better to have some open source online tool to describe a programming language itself. For example, the official PHP documentation looks perfect. It has: Support…
Dennis V
  • 574
  • 7
  • 19
0
votes
0 answers

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.141592653589793' I would like to use this feature…
krassowski
  • 13,598
  • 4
  • 60
  • 92
0
votes
2 answers

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.Server.MapPath("~/App_Data/XmlDocument.xml"))); There…
davidp04
  • 33
  • 1
  • 10
0
votes
1 answer

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 are multiple nested function calls: function…
djenning90
  • 197
  • 1
  • 9
1
2