30 karma · joined April 9, 2021
[Verifying my OpenPGP key: openpgp4fpr:D5A75F4998534FB47C839A9D03B34648D6DEB639]
What I find the most annoying is the lack of documentation of some of the nixpkgs functions. Some of the functions provided by import <nixpkgs> {}.lib appear to be the same as the ones builtin to the Nix language and there doesn't seem to be any clear guidance on when to use which version. I've also had to look at the source code to find out the difference between writeTextFile, writeText, writeTextDir, writeScript, and writeScriptBin. [The docs][1] explain writeTextFile, but the only documentation for the rest is ‘Many more commands wrap writeTextFile including writeText, writeTextDir, writeScript, and writeScriptBin. These are convenience functions over writeTextFile.’.
Additionally, it's a bit frustrating for me how all the documentation for nixpkgs — the lib functions, how to make a derivation, specific details for building packages in certain languages, how to contribute to nixpkgs, overriding packages/overlays etc — are in [one gigantic web page][2] that's quite slow to load and even slower to search for things in.
[1]: https://nixos.org/manual/nixpkgs/stable/#trivial-builder-wri...
[2]: https://nixos.org/manual/nixpkgs/stable/
(copied from my Lobsters comment https://lobste.rs/s/psfsfo/curse_nixos#c_y83hvy)
/// Does something.
///
/// - Parameters:
/// - bar: A description for bar.
/// - baz: A description for baz.
///
/// - Returns: Something fancy.
/// - Throws: Throws `SomeErrorType` if `bar` is invalid.
func foo(bar: String, baz: Int) throws -> Bool { /* ... */ }I mostly agree with the rest of the article’s recommendations, but don’t fully agree with their reasoning.
- Yes, namespaces should be avoided, but not because they generate extra code. Namespaces are not recommended anymore and modules (actual JS modules not TS’ `module`) is the recommended approach now.
- Yep, private fields are better for ensuring a field is truly private.
- I think decorators are fine to use if you’re prepared for your code to potentially break in the future if they’re standardised. Developers use new/unstable features all the time (e.g. stage 0/1 JS proposals via Babel, nightly Rust toolchain). And I don’t believe the lack of standardisation of decorators should be a factor in deciding whether to use a library that requires these.