Formerly /u/Zagorath on the alien site.

  • 11 Posts
  • 472 Comments
Joined 1 year ago
cake
Cake day: June 15th, 2023

help-circle





  • I just want to point out that “the solstice marks the start of the season” is not a universal fact. Here in Aus, we mark the start of summer as 1 December, and so if I were to take my perspective and apply it to the northern hemisphere, I would say that for you, Christmas is about a third of the way through winter.

    The difference here is technically referred to as “meteorological” vs “astronomical” seasons. I’ve always thought meteorological seasons make far more sense because they much better reflect reality. Winter is defined by cold weather and short days. The winter solstice is already very cold and it has the shortest day. It is absurd to put the shortest day at the very beginning of winter. If you wanted to have an astronomically-based calendar, the solstice should mark the very midpoint of winter, with the season starting precisely halfway between then and the autumnal equinox.

    But also, as the other user mentioned, some places have entirely different season systems. Seasons are, fundamentally, a human creation. The notion that weather patterns change throughout the year is a universal fact, but what we call those changes and how many categories we separate it into is human. Many cultures have their own systems with more or different seasons. Many tropical areas have traditionally only observed “wet” (or monsoon) and “dry” seasons. In ancient Egypt, the flooding of the Nile marked an important seasonal change. And South Asia uses a variety of different 6-season systems, such as the Hindu, Bengali, and Tamil calendars.


  • Yup absolutely. I mentioned web APIs because that’s what I’ve got the most experience with, but .h files, class library public interfaces, and any other time users who are not the implementor of the functionality might want to call it, the code they’ll be interacting with should be tailored to be good to interact with.


  • If the doco we’re talking about is specifically an API reference, then the documentation should be written first. Generate code stubs (can be as little as an interface, or include some basic actual code such as validating required properties are included, if you can get that code working purely with a generated template). Then write your actual functional implementation implementing those stubs.

    That way you can regenerate when you change the doco without overriding your implementation, but you are still forced to think about the user (as in the programmer implementing your API) experience first and foremost, rather than the often more haphazard result you can get if you write code first.

    For example, if writing a web API, write documentation in something like OpenAPI and generate stubs using Swagger.