Spring (April–June) and autumn (September–October) are the best times to visit. The gardens are at their most beautiful, the crowds are manageable, and the weather in the gardens is actually pleasant rather than punishing. July and August — especially weekends — are intensely crowded, with queues that can add an hour to every transition. If you must go in summer, arrive before the gates open.
The Musical Fountains shows (Grandes Eaux Musicales) run on Saturdays, Sundays, and certain public holidays from early April to late October. The fountains are choreographed to 17th and 18th-century Baroque music by composers who played at Versailles — Lully, Couperin, Charpentier. There is a separate ticket charge (around €10 on top of entry) and it's worth it; the gardens feel completely different when the water is moving.
In summer, the Gardens of Versailles also hosts night spectacles (Grandes Eaux Nocturnes) on Saturday evenings — the fountains lit up after dark with fireworks. These are popular and sell out; book in advance. The palace itself is closed on Mondays, which is also when many town restaurants take their day off.