In untyped languages (Python, Javascript specifically) find myself making a lot of bugs / wasting a lot of time because I forget what's in the objects I'm passing around. For example, I forget things like "is this property a string or an array of strings" (...the time I've spent debugging because I thought I was indexing into an array when I was actually indexing a string...)?

I try to document argument/return types, but there are several problems with this (at least, how I'm currently doing it):

  • when I'm developing a whole new feature it's hard to document and keep updating the docs as I go
  • when I'm importing lots of functions from other places it's easy to lose track of info elsewhere
  • I don't know how to document complex nested structure clearly — i.e. when a complicated object with lots of properties has an object property with a bunch of properties of its own

What's the best process / documentation method to keep track of these kinds of things and reduce my cognitive effort? An ideal solution would strike a balance with being able to prototype/develop quickly (not over-optimizing). Good open-source code examples would be especially welcome!

  • 1
    Both JavaScript and Python have ways to define classes with proper field definitions. This is exactly why you should be using them. Commented Oct 24, 2019 at 21:09

2 Answers 2



function doSomething(input)

What's input? I have no idea unless:

  • Debug and set breakpoint
  • Console.log (if running locally)
  • Or there are tests

No types, no idea.

Tests are living documentation that show what your code does, what is takes in, and what is coming out of it.

Very useful for JavaScript, I dare say mandatory. Otherwise, yes you will waste time and the code will have bugs.


I don't use JavaScript, but for Python my solution is to use type hints and some kind of linting/type checker.

I mostly develop in PyCharm which comes bundled with those tools, but there are other tools out there (probably for JS too).

For example, if I define a function as:

from typing import Dict, List, Optional, Union

def get_value(data: Dict, values: List[str], condition: Optional[bool]) -> Union[int, float]:
    # function body goes here

PyCharm now understands what data type the arguments corresponds to:

  • data is a dictionary
  • values is a list of strings
  • condition is an optional boolean (meaning None is also valid)
  • the function returns either an int or a float

This means that I get a warning if I, say, try to access a list method on data, or forget to return a numerical value.

Of course, this does not guarantee that you won't make any mistakes, and PyCharm's linting is also not perfect, but it has helped me a lot to quickly spot classic mistakes before running my code and wondering what went wrong.

Even without any linting, the type hints are very useful to understand what your code is doing at a glance, especially once you come back to it after a few days. At first it may feel cumbersome to add this "verbosity" to a dynamic language, but I find it simple and quick once you get used to it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.