Lambder lambder

Array

How Clojure's documentation can leapfrog other languages

Summary

I made a documentation generator that cashes in on Clojure's dynamism. See the play-cljs docs (a ClojureScript game library) for an example of its output.

The Problem

Like many of you, I've often wondered what my final regret will be on my deathbed. My best guess came to me in a dream recently. I was walking across the charred earth of an apocalyptic future world, maneuvering around the remains of the less fortunate. I was startled to find a young girl, barely holding onto her life. She murmured something to me. I asked her to repeat it, and she said more loudly: "I...wish your Clojure projects didn't have such crappy documentation."

nylas/N1 💌 An extensible desktop mail app built on the modern web.
black-screen/black-screen A terminal emulator for the 21st century.
shockone/black-screen A terminal emulator for the 21st century.
ptmt/react-native-macos React Native for macOS
docker/kitematic Visual Docker Container Management on Mac & Windows
kitematic/kitematic Visual Docker Container Management on Mac & Windows
davezuko/wirk-starter Get started with React, Redux, and React-Router!
TelescopeJS/Telescope 🔭 An open-source social news app built with Meteor & React
coryhouse/react-slingshot React + Redux starter kit / boile

Recently CSS has got a lot of negativity. But I would like to defend it and show, that with good naming convention CSS works pretty well.

My 3 developers team has just developed React.js application with 7668 lines of CSS (and just 2 !important). During one year of development we had 0 issues with CSS. No refactoring typos, no style leaks, no performance problems, possibly, it is the most stable part of our application.

Here are main principles we use to write CSS for modern (IE11+) browsers:

SUIT CSS naming conventions + SUIT CSS design principles;
PostCSS + CSSNext. Future CSS syntax like variables, nesting, and autoprefixer are good enough;
Flexbox is awesome. No need for grid framework;
Normalize.css, base styles and variables are solid foundation for all components;

Edit — February 2019

This gist had a far larger impact than I imagined it would, and apparently people are still finding it, so a quick update:

TC39 is currently moving forward with a slightly different version of TLA, referred to as 'variant B', in which a module with TLA doesn't block sibling execution. This vastly reduces the danger of parallelizable work happening in serial and thereby delaying startup, which was the concern that motivated me to write this gist
In the wild, we're seeing (async main(){...}()) as a substitute for TLA. This completely eliminates the blocking problem (yay!) but it's less powerful, and harder to statically analyse (boo). In other words the lack of TLA is causing real problems
Therefore, a version of TLA that solves the original issue is a valuable addition to the language, and I'm in full support of the current proposal, which you can read here.

I'll leave the rest of this document unedited, for archaeological

	""" Trains an agent with (stochastic) Policy Gradients on Pong. Uses OpenAI Gym. """
	import numpy as np
	import cPickle as pickle
	import gym

	# hyperparameters
	H = 200 # number of hidden layer neurons
	batch_size = 10 # every how many episodes to do a param update?
	learning_rate = 1e-4
	gamma = 0.99 # discount factor for reward

	import Html exposing (Html, text, button, div, p, ul, li)
	import Html.Attributes exposing (style)
	import Html.Events exposing (onClick)


	type OuterMsg =
	ContainerMsg InnerMsg \| View1Click \| View2Click


	main : Html OuterMsg

	-- See this document for more information on making Pong:
	-- http://elm-lang.org/blog/pong
	import Color exposing (..)
	import Collage exposing (..)
	import Element exposing (..)
	import Keyboard
	import Text
	import Time exposing (..)
	import Window exposing (Size)
	import Html.App as App

	import Html exposing (..)
	import Keyboard
	import Window exposing (Size)
	import AnimationFrame

	import Task
	import Html.App as App

	import Collage exposing (..)
	import Element exposing (..)

	import scala.collection.mutable.ListBuffer
	import org.scalacheck._, Arbitrary._, Prop._

	// a specs2 example showing that it works
	def e1 =
	forAll(distinctListOf[Int]) { ls =>
	ls.distinct === ls
	}.set(minTestsOk = 10000, maxSize = 1000)

	// distinct list of elements from a given arbitrary